tm: docs: reason header modparams and script function

- docs for:
	local_cancel_reason = 0|1
	e2e_cancel_reason = 0|1
	t_set_no_e2e_cancel_reason(0|1)
- regenerated README

NEWS

@@ -38,6 +38,23 @@ modules:
            blst_rpl_clear_ignore(mask): like blst_rpl_ignore(mask), but
             clears instead of setting.
 tm:
+   - reason header support (RFC3326) both for CANCELs generated due to a
+      received final reply and for hop by hop CANCELs generated because of a
+      received CANCEL.
+      E.g.: reason header added for a CANCEL generated after a 200 reply was
+            received on one of the branches "Reason: SIP;cause=200".
+      The reason header support can be turned on/off using either tm
+      module parameters or in the end to end CANCEL case also on a per
+      transaction basis, using a script function:
+       local_cancel_reason = 0 | 1 (default 1/on) - turns on adding reason
+         headers for CANCELs generated due to a final reply. Can be changed
+         at runtime.
+       e2e_cancel_reason = 0 | 1 (default 1/on) - turns on copying reason
+         headers from a received end to end CANCEL (the generated hop by hop
+         CANCELs will have the same reason headers as the received CANCEL).
+         Can be changed at runtime.
+       t_set_no_e2e_cancel_reason(0|1) - enable/disable cancel reason 
+         header copying on a per transaction basis (0 - enable, 1 disable).
    - t_reply() can be used both from the main/core onreply_route{} and tm
      onreply_route[...]{}s.
 

modules/tm/README

@@ -57,6 +57,8 @@ Juha Heinanen
         1.4.35. default_reason (string)
         1.4.36. disable_6xx_block (integer)
         1.4.37. local_ack_mode (integer)
+        1.4.38. local_cancel_reason (boolean)
+        1.4.39. e2e_cancel_reason (boolean)
 
    1.5. Functions
 
@@ -105,6 +107,7 @@ Juha Heinanen
         1.5.35. t_set_disable_failover(0|1)
         1.5.36. t_replicate(params)
         1.5.37. t_relay_to(proxy, flags)
+        1.5.38. t_set_no_e2e_cancel_reason(0|1)
 
    1.6. TM Module API
 
@@ -119,6 +122,9 @@ Juha Heinanen
               1.6.2.4. int t_continue(unsigned int hash_index, unsigned
                       int label, struct action *route)
 
+              1.6.2.5. int t_cancel_suspend(unsigned int hash_index,
+                      unsigned int label)
+
 1.1. Overview
 
    TM module enables stateful processing of SIP transactions. The main use
@@ -1131,12 +1137,48 @@ Note
 modparam("tm", "local_ack_mode", 1)
 ...
 
+1.4.38. local_cancel_reason (boolean)
+
+   Enables/disables adding reason headers (RFC 3326) for CANCELs generated
+   due to receiving a final reply. The reason header added will look like:
+   "Reason: SIP;cause=<final_reply_code>".
+
+   Default value is 1 (enabled).
+
+   Can be set at runtime, e.g.:
+        $ sercmd cfg.set_now_int tm local_cancel_reason 0
+
+   See also: e2e_cancel_reason.
+
+   Example 38. Set local_cancel_reason parameter
+...
+modparam("tm", "local_cancel_reason", "0")
+...
+
+1.4.39. e2e_cancel_reason (boolean)
+
+   Enables/disables adding reason headers (RFC 3326) for CANCELs generated
+   due to a received CANCEL. If enabled the reason headers from received
+   CANCELs will be copied into the generated hop-by-hop CANCELs.
+
+   Default value is 1 (enabled).
+
+   Can be changed at runtime, e.g.:
+        $ sercmd cfg.set_now_int tm e2e_cancel_reason 0
+
+   See also: t_set_no_e2e_cancel_reason() and local_cancel_reason.
+
+   Example 39. Set e2e_cancel_reason parameter
+...
+modparam("tm", "e2e_cancel_reason", "0")
+...
+
 1.5. Functions
 
    Revision History
    Revision $Revision$ $Date$
 
-1.5.1. t_relay_to_udp(ip, port), t_relay_to_udp(), t_relay_to_tcp(ip, port)
+1.5.1.  t_relay_to_udp(ip, port), t_relay_to_udp(), t_relay_to_tcp(ip, port)
 t_relay_to_tcp() t_relay_to_tls(ip, port) t_relay_to_tls()
 t_relay_to_sctp(ip, port) t_relay_to_sctp()
 
@@ -1156,7 +1198,7 @@ t_relay_to_sctp(ip, port) t_relay_to_sctp()
    derived from the message uri (using sip sepcific DNS lookups), but with
    the protocol corresponding to the function name.
 
-   Example 38. t_relay_to_udp usage
+   Example 40. t_relay_to_udp usage
 ...
 if (src_ip==10.0.0.0/8)
         t_relay_to_udp("1.2.3.4", "5060"); # sent to 1.2.3.4:5060 over udp
@@ -1164,7 +1206,7 @@ else
         t_relay_to_tcp(); # relay to msg. uri, but over tcp
 ...
 
-1.5.2. t_relay() t_relay(host, port)
+1.5.2.  t_relay() t_relay(host, port)
 
    Relay a message statefully either to the destination indicated in the
    current URI (if called without any parameters) or to the specified host
@@ -1183,7 +1225,7 @@ else
    Returns a negative value on failure--you may still want to send a
    negative reply upstream statelessly not to leave upstream UAC in lurch.
 
-   Example 39. t_relay usage
+   Example 41. t_relay usage
 ...
 if (!t_relay())
 {
@@ -1192,7 +1234,7 @@ if (!t_relay())
 };
 ...
 
-1.5.3. t_on_failure(failure_route)
+1.5.3.  t_on_failure(failure_route)
 
    Sets failure routing block, to which control is passed after a
    transaction completed with a negative result but before sending a final
@@ -1212,7 +1254,7 @@ if (!t_relay())
    Meaning of the parameters is as follows:
      * failure_route - Failure route block to be called.
 
-   Example 40. t_on_failure usage
+   Example 42. t_on_failure usage
 ...
 route {
     t_on_failure("1");
@@ -1229,7 +1271,7 @@ failure_route[1] {
    See test/onr.cfg for a more complex example of combination of serial
    with parallel forking.
 
-1.5.4. t_on_reply(onreply_route)
+1.5.4.  t_on_reply(onreply_route)
 
    Sets the reply routing block, to which control is passed when a reply
    for the current transaction is received. Note that the set of commands
@@ -1238,7 +1280,7 @@ failure_route[1] {
    Meaning of the parameters is as follows:
      * onreply_route - Onreply route block to be called.
 
-   Example 41. t_on_reply usage
+   Example 43. t_on_reply usage
 ...
 loadmodule "/usr/local/lib/ser/modules/nathelper.so"
 ...
@@ -1259,7 +1301,7 @@ es');
         }
 }
 
-1.5.5. t_on_branch(branch_route)
+1.5.5.  t_on_branch(branch_route)
 
    Sets the branch routing block, to which control is passed after forking
    (when a new branch is created). For now branch routes are intended only
@@ -1270,7 +1312,7 @@ es');
    Meaning of the parameters is as follows:
      * branch_route - branch route block to be called.
 
-   Example 42. t_on_branch usage
+   Example 44. t_on_branch usage
 ...
 route {
         t_on_branch("1");
@@ -1283,12 +1325,12 @@ branch_route[1] {
         }
 }
 
-1.5.6. append_branch()
+1.5.6.  append_branch()
 
    Similarly to t_fork_to, it extends destination set by a new entry. The
    difference is that current URI is taken as new entry.
 
-   Example 43. append_branch usage
+   Example 45. append_branch usage
 ...
 set_user("john");
 t_fork();
@@ -1297,13 +1339,13 @@ t_fork();
 t_relay();
 ...
 
-1.5.7. t_newtran()
+1.5.7.  t_newtran()
 
    Creates a new transaction, returns a negative value on error. This is
    the only way a script can add a new transaction in an atomic way.
    Typically, it is used to deploy a UAS.
 
-   Example 44. t_newtran usage
+   Example 46. t_newtran usage
 ...
 if (t_newtran()) {
     log("UAS logic");
@@ -1313,7 +1355,7 @@ if (t_newtran()) {
 
    See test/uas.cfg for more examples.
 
-1.5.8. t_reply(code, reason_phrase)
+1.5.8.  t_reply(code, reason_phrase)
 
    Sends a stateful reply after a transaction has been established. See
    t_newtran for usage.
@@ -1322,12 +1364,12 @@ if (t_newtran()) {
      * code - Reply code number.
      * reason_phrase - Reason string.
 
-   Example 45. t_reply usage
+   Example 47. t_reply usage
 ...
 t_reply("404", "Not found");
 ...
 
-1.5.9. t_lookup_request()
+1.5.9.  t_lookup_request()
 
    Checks if a transaction exists. Returns a positive value if so,
    negative otherwise. Most likely you will not want to use it, as a
@@ -1335,33 +1377,33 @@ t_reply("404", "Not found");
    none was found. However this is safely (atomically) done using
    t_newtran.
 
-   Example 46. t_lookup_request usage
+   Example 48. t_lookup_request usage
 ...
 if (t_lookup_request()) {
     ...
 };
 ...
 
-1.5.10. t_retransmit_reply()
+1.5.10.  t_retransmit_reply()
 
    Retransmits a reply sent previously by UAS transaction.
 
-   Example 47. t_retransmit_reply usage
+   Example 49. t_retransmit_reply usage
 ...
 t_retransmit_reply();
 ...
 
-1.5.11. t_release()
+1.5.11.  t_release()
 
    Remove transaction from memory (it will be first put on a wait timer to
    absorb delayed messages).
 
-   Example 48. t_release usage
+   Example 50. t_release usage
 ...
 t_release();
 ...
 
-1.5.12. t_forward_nonack() t_forward_nonack(ip, port)
+1.5.12.  t_forward_nonack() t_forward_nonack(ip, port)
 t_forward_nonack_udp(ip, port) t_forward_nonack_tcp(ip, port)
 t_forward_nonack_tls(ip, port) t_forward_nonack_sctp(ip, port)
 
@@ -1371,12 +1413,12 @@ t_forward_nonack_tls(ip, port) t_forward_nonack_sctp(ip, port)
      * ip - IP address where the message should be sent.
      * port - Port number.
 
-   Example 49. t_forward_nonack usage
+   Example 51. t_forward_nonack usage
 ...
 t_forward_nonack("1.2.3.4", "5060");
 ...
 
-1.5.13. t_set_fr(fr_inv_timeout [, fr_timeout])
+1.5.13.  t_set_fr(fr_inv_timeout [, fr_timeout])
 
    Sets the fr_inv_timeout and optionally fr_timeout for the current
    transaction or for transactions created during the same script
@@ -1394,7 +1436,7 @@ t_forward_nonack("1.2.3.4", "5060");
 
    See also: fr_timer, fr_inv_timer, t_reset_fr().
 
-   Example 50. t_set_fr usage
+   Example 52. t_set_fr usage
 ...
 route {
         t_set_fr(10000); # set only fr invite timeout to 10s
@@ -1410,7 +1452,7 @@ branch_route[1] {
         }
 }
 
-1.5.14. t_reset_fr()
+1.5.14.  t_reset_fr()
 
    Resets the fr_inv_timer and fr_timer for the current transaction to the
    default values (set using the tm module parameters fr_inv_timer and
@@ -1421,7 +1463,7 @@ branch_route[1] {
 
    See also: fr_timer, fr_inv_timer, t_set_fr.
 
-   Example 51. t_reset_fr usage
+   Example 53. t_reset_fr usage
 ...
 route {
 ...
@@ -1429,7 +1471,7 @@ route {
 ...
 }
 
-1.5.15. t_set_max_lifetime(inv_lifetime, noninv_lifetime)
+1.5.15.  t_set_max_lifetime(inv_lifetime, noninv_lifetime)
 
    Sets the maximum lifetime for the current INVITE or non-INVITE
    transaction, or for transactions created during the same script
@@ -1447,7 +1489,7 @@ route {
 
    See also: max_inv_lifetime, max_noninv_lifetime, t_reset_max_lifetime.
 
-   Example 52. t_set_max_lifetime usage
+   Example 54. t_set_max_lifetime usage
 ...
 route {
     if (src_ip=1.2.3.4)
@@ -1458,7 +1500,7 @@ route {
                                           # INVITE and to 15s if not
 }
 
-1.5.16. t_reset_max_lifetime()
+1.5.16.  t_reset_max_lifetime()
 
    Resets the the maximum lifetime for the current INVITE or non-INVITE
    transaction to the default value (set using the tm module parameter
@@ -1469,7 +1511,7 @@ route {
 
    See also: max_inv_lifetime, max_noninv_lifetime, t_set_max_lifetime.
 
-   Example 53. t_reset_max_lifetime usage
+   Example 55. t_reset_max_lifetime usage
 ...
 route {
 ...
@@ -1477,7 +1519,7 @@ route {
 ...
 }
 
-1.5.17. t_set_retr(retr_t1_interval, retr_t2_interval)
+1.5.17.  t_set_retr(retr_t1_interval, retr_t2_interval)
 
    Sets the retr_t1_interval and retr_t2_interval for the current
    transaction or for transactions created during the same script
@@ -1507,7 +1549,7 @@ route {
 
    See also: retr_timer1, retr_timer2, t_reset_retr().
 
-   Example 54. t_set_retr usage
+   Example 56. t_set_retr usage
 ...
 route {
         t_set_retr(250, 0); # set only T1 to 250 ms
@@ -1523,7 +1565,7 @@ branch_route[1] {
         }
 }
 
-1.5.18. t_reset_retr()
+1.5.18.  t_reset_retr()
 
    Resets the retr_timer1 and retr_timer2 for the current transaction to
    the default values (set using the tm module parameters retr_timer1 and
@@ -1534,7 +1576,7 @@ branch_route[1] {
 
    See also: retr_timer1, retr_timer2, t_set_retr.
 
-   Example 55. t_reset_retr usage
+   Example 57. t_reset_retr usage
 ...
 route {
 ...
@@ -1542,7 +1584,7 @@ route {
 ...
 }
 
-1.5.19. t_set_auto_inv_100(0|1)
+1.5.19.  t_set_auto_inv_100(0|1)
 
    Switch automatically sending 100 replies to INVITEs on/off on a per
    transaction basis. It overrides the auto_inv_100 value for the current
@@ -1550,7 +1592,7 @@ route {
 
    See also: auto_inv_100.
 
-   Example 56. t_set_auto_inv_100 usage
+   Example 58. t_set_auto_inv_100 usage
 ...
 route {
 ...
@@ -1559,12 +1601,12 @@ route {
 ...
 }
 
-1.5.20. t_branch_timeout()
+1.5.20.  t_branch_timeout()
 
    Returns true if the failure route is executed for a branch that did
    timeout. It can be used only from the failure_route.
 
-   Example 57. t_branch_timeout usage
+   Example 59. t_branch_timeout usage
 ...
 failure_route[0]{
         if (t_branch_timeout()){
@@ -1573,13 +1615,13 @@ failure_route[0]{
         }
 }
 
-1.5.21. t_branch_replied()
+1.5.21.  t_branch_replied()
 
    Returns true if the failure route is executed for a branch that did
    receive at least one reply in the past (the "current" reply is not
    taken into account). It can be used only from the failure_route.
 
-   Example 58. t_branch_replied usage
+   Example 60. t_branch_replied usage
 ...
 failure_route[0]{
         if (t_branch_timeout()){
@@ -1591,12 +1633,12 @@ failure_route[0]{
         }
 }
 
-1.5.22. t_any_timeout()
+1.5.22.  t_any_timeout()
 
    Returns true if at least one of the current transactions branches did
    timeout.
 
-   Example 59. t_any_timeout usage
+   Example 61. t_any_timeout usage
 ...
 failure_route[0]{
         if (!t_branch_timeout()){
@@ -1607,13 +1649,13 @@ failure_route[0]{
         }
 }
 
-1.5.23. t_any_replied()
+1.5.23.  t_any_replied()
 
    Returns true if at least one of the current transactions branches did
    receive some reply in the past. If called from a failure or onreply
    route, the "current" reply is not taken into account.
 
-   Example 60. t_any_replied usage
+   Example 62. t_any_replied usage
 ...
 onreply_route[0]{
         if (!t_any_replied()){
@@ -1622,12 +1664,12 @@ onreply_route[0]{
         }
 }
 
-1.5.24. t_grep_status("code")
+1.5.24.  t_grep_status("code")
 
    Returns true if "code" is the final reply received (or locally
    generated) in at least one of the current transactions branches.
 
-   Example 61. t_grep_status usage
+   Example 63. t_grep_status usage
 ...
 onreply_route[0]{
         if (t_grep_status("486")){
@@ -1636,11 +1678,11 @@ onreply_route[0]{
         }
 }
 
-1.5.25. t_is_canceled()
+1.5.25.  t_is_canceled()
 
    Returns true if the current transaction was canceled.
 
-   Example 62. t_is_canceled usage
+   Example 64. t_is_canceled usage
 ...
 failure_route[0]{
         if (t_is_canceled()){
@@ -1649,12 +1691,12 @@ failure_route[0]{
         }
 }
 
-1.5.26. t_is_expired()
+1.5.26.  t_is_expired()
 
    Returns true if the current transaction has already been expired, i.e.
    the max_inv_lifetime/max_noninv_lifetime interval has already elapsed.
 
-   Example 63. t_is_expired usage
+   Example 65. t_is_expired usage
 ...
 failure_route[0]{
         if (t_is_expired()){
@@ -1663,7 +1705,7 @@ failure_route[0]{
         }
 }
 
-1.5.27. t_relay_cancel()
+1.5.27.  t_relay_cancel()
 
    Forwards the CANCEL if the corresponding INVITE transaction exists. The
    function is supposed to be used at the very beginning of the script,
@@ -1675,7 +1717,7 @@ failure_route[0]{
    CANCELs were successfully sent to the pending branches, true if the
    INVITE was not found, and false in case of any error.
 
-   Example 64. t_relay_cancel usage
+   Example 66. t_relay_cancel usage
 if (method == CANCEL) {
         if (!t_relay_cancel()) {  # implicit drop if relaying was successful,
                                   # nothing to do
@@ -1688,7 +1730,7 @@ if (method == CANCEL) {
         # do the same as for INVITEs
 }
 
-1.5.28. t_lookup_cancel(), t_lookup_cancel(1)
+1.5.28.  t_lookup_cancel(), t_lookup_cancel(1)
 
    Returns true if the corresponding INVITE transaction exists for a
    CANCEL request. The function can be called at the beginning of the
@@ -1702,7 +1744,7 @@ if (method == CANCEL) {
    overwritten with the flags of the INVITE. isflagset() can be used to
    check the flags of the previously forwarded INVITE in this case.
 
-   Example 65. t_lookup_cancel usage
+   Example 67. t_lookup_cancel usage
 if (method == CANCEL) {
         if (t_lookup_cancel()) {
                 log("INVITE transaction exists");
@@ -1720,7 +1762,7 @@ if (method == CANCEL) {
         # do the same as for INVITEs
 }
 
-1.5.29. t_drop_replies([mode])
+1.5.29.  t_drop_replies([mode])
 
    Drops all the previously received replies in failure_route block to
    make sure that none of them is picked up again.
@@ -1732,7 +1774,7 @@ if (method == CANCEL) {
    Dropping replies works only if a new branch is added to the
    transaction, or it is explicitly replied in the script!
 
-   Example 66. t_drop_replies() usage
+   Example 68. t_drop_replies() usage
 ...
 failure_route[0]{
         if (t_check_status("5[0-9][0-9]")){
@@ -1748,7 +1790,7 @@ failure_route[0]{
         }
 }
 
-1.5.30. t_save_lumps()
+1.5.30.  t_save_lumps()
 
    Forces the modifications of the processed SIP message to be saved in
    shared memory before t_relay() is called. The new branches which are
@@ -1763,7 +1805,7 @@ failure_route[0]{
    The transaction must be created by t_newtran() before calling
    t_save_lumps().
 
-   Example 67. t_save_lumps() usage
+   Example 69. t_save_lumps() usage
 route {
         ...
         t_newtran();
@@ -1788,7 +1830,7 @@ failure_route[1] {
         t_relay();
 }
 
-1.5.31. t_load_contacts()
+1.5.31.  t_load_contacts()
 
    This is the first of the two functions that can be used to implement
    serial/parallel forking based on the q value of individual branches in
@@ -1833,7 +1875,7 @@ failure_route[1] {
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 68. t_load_contacts usage
+   Example 70. t_load_contacts usage
 ...
 if (!t_load_contacts()) {
         sl_send_reply("500", "Server Internal Error - Cannot load contacts");
@@ -1841,7 +1883,7 @@ if (!t_load_contacts()) {
 };
 ...
 
-1.5.32. t_next_contacts()
+1.5.32.  t_next_contacts()
 
    The function t_next_contacts is the second of the two functions that
    can be used to implement serial/parallel forking based on the q value
@@ -1885,7 +1927,7 @@ if (!t_load_contacts()) {
    especially if you expect to have many serially forked branches. See the
    documentation of that parameter for more details.
 
-   Example 69. t_next_contacts usage
+   Example 71. t_next_contacts usage
 ...
 # First call after t_load_contacts() when transaction does not exist yet
 # and contacts should be available
@@ -1904,7 +1946,7 @@ if (!t_next_contacts()) {
 };
 ...
 
-1.5.33. t_check_trans()
+1.5.33.  t_check_trans()
 
    t_check_trans() can be used to quickly check if a message belongs or is
    related to a transaction. It behaves differently for different types of
@@ -1949,12 +1991,12 @@ Note
 
    See also: t_lookup_request(), t_lookup_cancel().
 
-   Example 70. t_check_trans usage
+   Example 72. t_check_trans usage
 if ( method == "CANCEL" && !t_check_trans())
         sl_reply("403", "cancel out of the blue forbidden");
 # note: in this example t_check_trans() can be replaced by t_lookup_cancel()
 
-1.5.34. t_set_disable_6xx(0|1)
+1.5.34.  t_set_disable_6xx(0|1)
 
    Turn off/on 6xx replies special rfc conformant handling on a per
    transaction basis. If turned off (t_set_disable_6xx("1")) 6XXs will be
@@ -1964,7 +2006,7 @@ if ( method == "CANCEL" && !t_check_trans())
 
    See also: disable_6xx_block.
 
-   Example 71. t_set_disable_6xx usage
+   Example 73. t_set_disable_6xx usage
 ...
 route {
 ...
@@ -1973,13 +2015,13 @@ route {
 ...
 }
 
-1.5.35. t_set_disable_failover(0|1)
+1.5.35.  t_set_disable_failover(0|1)
 
    Turn off/on dns failover on a per transaction basis.
 
    See also: use_dns_failover.
 
-   Example 72. t_set_disable_failover usage
+   Example 74. t_set_disable_failover usage
 ...
 route {
 ...
@@ -1988,7 +2030,7 @@ route {
 ...
 }
 
-1.5.36. t_replicate(params)
+1.5.36.  t_replicate(params)
 
    Replicate the SIP request to a specific address.
 
@@ -2010,7 +2052,7 @@ route {
      * hostport - address in "host:port" format. It can be given via an
        AVP.
 
-   Example 73. t_replicate usage
+   Example 75. t_replicate usage
 ...
 # sent to 1.2.3.4:5060 over tcp
 t_replicate("sip:1.2.3.4:5060;transport=tcp");
@@ -2023,7 +2065,7 @@ t_replicate("sip:$var(h);transport=tls");
 t_replicate_to_udp("1.2.3.4", "5060");
 ...
 
-1.5.37. t_relay_to(proxy, flags)
+1.5.37.  t_relay_to(proxy, flags)
 
    Forward the SIP request to a specific address, controlling internal
    behavior via flags.
@@ -2045,7 +2087,7 @@ t_replicate_to_udp("1.2.3.4", "5060");
             effect anymore).
           + 0x04 - disable dns failover.
 
-   Example 74. t_replicate usage
+   Example 76. t_replicate usage
 ...
 # sent to 1.2.3.4:5060 over tcp
 t_relay_to("tcp:1.2.3.4:5060");
@@ -2057,6 +2099,27 @@ t_relay_to("tls:1.2.3.4");
 t_relay_to("0x01");
 ...
 
+1.5.38.  t_set_no_e2e_cancel_reason(0|1)
+
+   Enables/disables reason header (RFC 3326) copying from the triggering
+   received CANCEL to the generated hop-by-hop CANCEL. 0 enables and 1
+   disables.
+
+   It overrides the e2e_cancel_reason setting (module parameter) for the
+   current transaction.
+
+   See also: e2e_cancel_reason.
+
+   Example 77. t_set_no_e2e_cancel_reason usage
+...
+route {
+...
+        if (src_ip!=10.0.0.0/8) #  don't trust CANCELs from the outside
+                t_set_no_e2e_cancel_reason(1); # turn off CANCEL reason header c
+opying
+...
+}
+
 1.6. TM Module API
 
    Revision History
@@ -2126,7 +2189,7 @@ end of body
 
 1.6.2. Functions
 
-1.6.2.1. register_tmcb(cb_type, cb_func)
+1.6.2.1.  register_tmcb(cb_type, cb_func)
 
    For programmatic use only--register a function to be called back on an
    event. See t_hooks.h for more details.
@@ -2135,7 +2198,7 @@ end of body
      * cb_type - Callback type.
      * cb_func - Callback function.
 
-1.6.2.2. load_tm(*import_structure)
+1.6.2.2.  load_tm(*import_structure)
 
    For programmatic use only--import exported TM functions. See the acc
    module for an example of use.
@@ -2143,7 +2206,7 @@ end of body
    Meaning of the parameters is as follows:
      * import_structure - Pointer to the import structure.
 
-1.6.2.3. int t_suspend(struct sip_msg *msg, unsigned int *hash_index,
+1.6.2.3.  int t_suspend(struct sip_msg *msg, unsigned int *hash_index,
 unsigned int *label)
 
    For programmatic use only. This function together with t_continue() can
@@ -2181,7 +2244,7 @@ unsigned int *label)
    t_suspend() should return 0 to make sure that the script processing
    does not continue.
 
-1.6.2.4. int t_continue(unsigned int hash_index, unsigned int label, struct
+1.6.2.4.  int t_continue(unsigned int hash_index, unsigned int label, struct
 action *route)
 
    For programmatic use only. This function is the pair of t_suspend(),
@@ -2196,3 +2259,19 @@ action *route)
      * route - route block to execute.
 
    Return value: 0 - success, <0 - error.
+
+1.6.2.5.  int t_cancel_suspend(unsigned int hash_index, unsigned int label)
+
+   For programmatic use only. This function is for revoking t_suspend()
+   from the same process as it was executed before. t_cancel_suspend() can
+   be used when something fails after t_suspend() has already been
+   executed and it turns out that the transcation should not have been
+   suspended. The function cancels the FR timer of the transacation.
+
+   The message lumps are saved by t_suspend() which cannot be restored.
+
+   Meaning of the parameters is as follows:
+     * hash_index - transaction identifier.
+     * label - transaction identifier.
+
+   Return value: 0 - success, <0 - error.

modules/tm/doc/functions.xml

@@ -1224,7 +1224,9 @@ if (!t_next_contacts()) {
 				INVITE transactions) it will return true if the corresponding
 				INVITE transaction is found and still active and false if not.
 				</para>
-				<note>Note that the e2e ACK matching is more of a hint
+				<note>
+				<para>
+				Note that the e2e ACK matching is more of a hint
 				then a certainty. A delayed e2e ACK might arrive after the
 				transaction wait time elapses, when the INVITE transaction no
 				longer exists and thus would not match anything. There are
@@ -1232,6 +1234,7 @@ if (!t_next_contacts()) {
 				for e2e ACK matching (since this is not needed for a statefull
 				proxy and it requires additional memory, tm will not keep this
 				information unless needed by some other module or callbacks).
+				</para>
 				</note>
 			</listitem>
 			<listitem>
@@ -1332,27 +1335,27 @@ route {
 	<para>
 		There are several function prototypes:
 		<itemizedlist>
-		<listitem>
+		<listitem><para>
 	    <function>t_replicate(uri)</function>,
-		</listitem>
-		<listitem>
+		</para></listitem>
+		<listitem><para>
 	    <function>t_replicate(host, port)</function>,
-		</listitem>
-		<listitem>
+		</para></listitem>
+		<listitem><para>
 	    <function>t_replicat_udp(host, port)</function>
-		</listitem>
-		<listitem>
+		</para></listitem>
+		<listitem><para>
 	    <function>t_replicate_tcp(host, port)</function>
-		</listitem>
-		<listitem>
+		</para></listitem>
+		<listitem><para>
 	    <function>t_replicate_tls(host, port)</function>
-		</listitem>
-		<listitem>
+		</para></listitem>
+		<listitem><para>
 	    <function>t_replicate_sctp(host, port)</function>
-		</listitem>
-		<listitem>
+		</para></listitem>
+		<listitem><para>
 	    <function>t_replicate_to(proto, hostport)</function>
-		</listitem>
+		</para></listitem>
 		</itemizedlist>
 	</para>
 	<para>Meaning of the parameters is as follows:</para>
@@ -1408,18 +1411,18 @@ t_replicate_to_udp("1.2.3.4", "5060");
 	<para>
 		There are several function prototypes:
 		<itemizedlist>
-		<listitem>
+		<listitem><para>
 	    <function>t_relay_to()</function>,
-		</listitem>
-		<listitem>
+		</para></listitem>
+		<listitem><para>
 	    <function>t_relay_to(proxy)</function>,
-		</listitem>
-		<listitem>
+		</para></listitem>
+		<listitem><para>
 	    <function>t_relay_to(flags)</function>
-		</listitem>
-		<listitem>
+		</para></listitem>
+		<listitem><para>
 	    <function>t_relay_to(proxy, flags)</function>
-		</listitem>
+		</para></listitem>
 		</itemizedlist>
 	</para>
 	<para>Meaning of the parameters is as follows:</para>
@@ -1468,4 +1471,36 @@ t_relay_to("0x01");
 	</example>
     </section>
 
+
+	<section id="t_set_no_e2e_cancel_reason">
+	<title>
+		<function>t_set_no_e2e_cancel_reason(0|1)</function>
+	</title>
+	<para>
+		Enables/disables reason header (RFC 3326) copying from the triggering
+		received CANCEL to the generated hop-by-hop CANCEL. 0 enables and
+		1 disables.
+	</para>
+	<para>
+		It overrides the <varname>e2e_cancel_reason</varname> setting (module
+		 parameter) for the current transaction.
+	</para>
+	<para>
+		See also: <varname>e2e_cancel_reason</varname>.
+	</para>
+	<example>
+		<title><function>t_set_no_e2e_cancel_reason</function> usage</title>
+		<programlisting>
+...
+route {
+...
+	if (src_ip!=10.0.0.0/8) #  don't trust CANCELs from the outside
+		t_set_no_e2e_cancel_reason(1); # turn off CANCEL reason header copying
+...
+}
+		</programlisting>
+	</example>
+	</section>
+
+
 </section>

modules/tm/doc/params.xml

@@ -45,9 +45,11 @@ modparam("tm", "fr_timer", 10000)
 	</para>
 	<para>
 	</para>
+	<para>
 		Note: this timer can be restarted when a provisional response is
 		received. For more details see
 		<varname>restart_fr_on_each_reply</varname>.
+	</para>
 	<para>
 	    Default value is 120000 ms (120 seconds).
 	</para>
@@ -1142,11 +1144,11 @@ modparam("tm", "disable_6xx_block", 1)
 		reply.
 		</para></listitem>
 	</itemizedlist>
-	<note>
+	<note><para>
 	Mode 1 and 2 break the rfc, but are useful to deal with some simple UAs
 	behind the NAT cases (no different routing for the ACK and the contact 
 	contains an address behind the NAT).
-	</note>
+	</para></note>
 	<para>
 		The default value is 0 (rfc conformant behaviour).
 	</para>
@@ -1166,4 +1168,66 @@ modparam("tm", "local_ack_mode", 1)
 	</example>
 	</section>
 
+
+	<section id="local_cancel_reason">
+		<title><varname>local_cancel_reason</varname> (boolean)</title>
+		<para>
+			Enables/disables adding reason headers (RFC 3326) for CANCELs
+			generated due to receiving a final reply. The reason header added
+			will look like: "Reason: SIP;cause=&lt;final_reply_code&gt;".
+		</para>
+		<para>
+			Default value is 1 (enabled).
+		</para>
+		<para>
+			Can be set at runtime, e.g.:
+			<programlisting>
+	$ sercmd cfg.set_now_int tm local_cancel_reason 0
+			</programlisting>
+		</para>
+		<para>
+			See also: <varname>e2e_cancel_reason</varname>.
+		</para>
+		<example>
+			<title>Set <varname>local_cancel_reason</varname> parameter</title>
+			<programlisting>
+...
+modparam("tm", "local_cancel_reason", "0")
+...
+			</programlisting>
+		</example>
+	</section>
+
+
+	<section id="e2e_cancel_reason">
+		<title><varname>e2e_cancel_reason</varname> (boolean)</title>
+		<para>
+			Enables/disables adding reason headers (RFC 3326) for CANCELs
+			generated due to a received CANCEL.  If enabled the reason headers
+			from received CANCELs will be copied into the generated hop-by-hop
+			CANCELs.
+		</para>
+		<para>
+			Default value is 1 (enabled).
+		</para>
+		<para>
+			Can be changed at runtime, e.g.:
+			<programlisting>
+	$ sercmd cfg.set_now_int tm e2e_cancel_reason 0
+			</programlisting>
+		</para>
+		<para>
+			See also: <function>t_set_no_e2e_cancel_reason()</function> and
+						<varname>local_cancel_reason</varname>.
+		</para>
+		<example>
+			<title>Set <varname>e2e_cancel_reason</varname> parameter</title>
+			<programlisting>
+...
+modparam("tm", "e2e_cancel_reason", "0")
+...
+			</programlisting>
+		</example>
+	</section>
+
 </section>

modules/tm/doc/tm.xml

@@ -1,6 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
-   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+	[ <!ENTITY % local.common.attrib
+	 "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
+	 <!-- Include general documentation entities -->
+	 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+	 %docentities;
+	]
+>
 
 <section id="tm" xmlns:xi="http://www.w3.org/2001/XInclude">
     <sectioninfo>