TCP Ops module

Camille Oudot

   Orange

Olle E. Johansson

   Edvina AB

   Copyright © 2015 Orange

   Copyright © 2015 Edvina AB, Sollentuna, Sweden
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Parameters

              2.1. closed_event (int)
              2.2. event_callback (str)

        3. Functions

              3.1. tcp_conid_alive(conid)
              3.2. tcp_conid_state(conid)
              3.3. tcp_keepalive_enable([conid], idle, count, interval)
              3.4. tcp_keepalive_disable([conid])
              3.5. tcp_set_connection_lifetime([conid], lifetime)
              3.6. tcp_enable_closed_event([conid])
              3.7. tcp_get_conid(hostport, pvname)
              3.8. tcp_set_otcpid(conid)
              3.9. tcp_set_otcpid_flag(mode)
              3.10. tcp_close_connection([conid])

        4. Event routes

              4.1. tcp:closed
              4.2. tcp:timeout
              4.3. tcp:reset
              4.4. Example

   List of Examples

   1.1. Set closed_event parameter
   1.2. Set event_callback parameter
   1.3. tcp_conid_alive usage
   1.4. tcp_conid_state usage
   1.5. tcp_keepalive_enable usage
   1.6. tcp_keepalive_disable usage
   1.7. tcp_set_connection_lifetime usage
   1.8. tcp_set_closed_event usage
   1.9. tcp_get_conid usage
   1.10. tcp_set_otcpid usage
   1.11. tcp_set_otcpid_flag usage
   1.12. tcp_close_connection usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Parameters

        2.1. closed_event (int)
        2.2. event_callback (str)

   3. Functions

        3.1. tcp_conid_alive(conid)
        3.2. tcp_conid_state(conid)
        3.3. tcp_keepalive_enable([conid], idle, count, interval)
        3.4. tcp_keepalive_disable([conid])
        3.5. tcp_set_connection_lifetime([conid], lifetime)
        3.6. tcp_enable_closed_event([conid])
        3.7. tcp_get_conid(hostport, pvname)
        3.8. tcp_set_otcpid(conid)
        3.9. tcp_set_otcpid_flag(mode)
        3.10. tcp_close_connection([conid])

   4. Event routes

        4.1. tcp:closed
        4.2. tcp:timeout
        4.3. tcp:reset
        4.4. Example

1. Overview

   This module allows Kamailio to control the TCP connection options (such
   as the keepalive mechanism), on demand, and on a per-socket basis.

   Note: the keepalive functions only work on systems with the
   HAVE_TCP_KEEPIDLE, HAVE_TCP_KEEPCNT and HAVE_TCP_KEEPINTVL macros
   defined (Linux, FreeBSD, DragonFly BSD, NetBSD).

2. Parameters

   2.1. closed_event (int)
   2.2. event_callback (str)

2.1. closed_event (int)

   If set to 0 (globally disabled), the "tcp:closed" event route will
   never be called on TCP disconnections.

   If set to 1 (globally enabled), the "tcp:closed" event route will
   always be called on TCP disconnections.

   If set to 2 ("manual" mode), the "tcp:closed" event route will only be
   called on TCP connections for which tcp_enable_closed_event() has been
   applied, when a disconnection occurs.

   Default value is 1 (globally enabled).

   Example 1.1. Set closed_event parameter
...
modparam("tcpops", "closed_event", 0)
...

2.2. event_callback (str)

   The name of the function in the kemi configuration file (embedded
   scripting language such as Lua, Python, ...) to be executed instead of
   event_route[...] blocks.

   The function receives a string parameter with the name of the event,
   the values are: 'tcp:closed', 'tcp:timeout', 'tcp:reset'.

   Default value is 'empty' (no function is executed for events).

   Example 1.2. Set event_callback parameter
...
modparam("tcpops", "event_callback", "ksr_tcpops_event")
...
-- event callback function implemented in Lua
function ksr_tcpops_event(evname)
        KSR.info("===== tcpops module triggered event: " .. evname .. "\n");
        return 1;
end
...

3. Functions

   3.1. tcp_conid_alive(conid)
   3.2. tcp_conid_state(conid)
   3.3. tcp_keepalive_enable([conid], idle, count, interval)
   3.4. tcp_keepalive_disable([conid])
   3.5. tcp_set_connection_lifetime([conid], lifetime)
   3.6. tcp_enable_closed_event([conid])
   3.7. tcp_get_conid(hostport, pvname)
   3.8. tcp_set_otcpid(conid)
   3.9. tcp_set_otcpid_flag(mode)
   3.10. tcp_close_connection([conid])

3.1.  tcp_conid_alive(conid)

   Check the state of a TCP or WS connection ID

   Meaning of the parameters is as follows:
     * conid (optional): the Kamailio internal connection id (as in the
       $conid pseudovariable).

   Return values:

   1: Connection is OK

   -1: Connection has errors, does not exist or is about to be closed)

   Example 1.3. tcp_conid_alive usage
...
        $var(conid) = $conid;
        if(!tcp_conid_alive("$var(conid)")) {
                xlog("L_ERR", "Connection $conid can no longer be used\n");
        }
...

3.2.  tcp_conid_state(conid)

   Check the state of a TCP or WS connection ID

   Meaning of the parameters is as follows:
     * conid (optional): the Kamailio internal connection id (as in the
       $conid pseudovariable).

   Return values:

   1: Connection is OK

   2: Socket is accepting incoming connections

   3: Socket is setting up outgoing connection

   -1: Connection does not exist (or was closed)

   -2: Socket has reached EOF

   -3: Socket error has occurred. Connection will likely close.

   -4: Socket is in unknown bad state. Connection will likely close.

   Example 1.4. tcp_conid_state usage
...
        if(!tcp_conid_state("$var(conid)")) {
                xlog("L_ERR", "Connection $conid is closed or malfunctional\n");
        }
...

3.3.  tcp_keepalive_enable([conid], idle, count, interval)

   Enables keepalive on a TCP connection.

   Meaning of the parameters is as follows:
     * conid (optional): the Kamailio internal connection id on which TCP
       keepalive will be enabled. If no parameter is given, the keepalive
       mechanism will be enabled on the current message source connection.
     * idle (seconds): the time before the first keepalive packet is sent
       out.
     * count: number of non-acked keepalive before resetting the
       connection.
     * interval (seconds): time between two keepalive probes.

   Returns 1 on success, -1 on failure.

   Example 1.5. tcp_keepalive_enable usage
request_route {
        if (is_method("INVITE")) {
                $avp(caller_conid) = $conid;
                t_on_reply("foo");
        }
        ...
}

onreply_route[foo] {
        if (is_method("INVITE") && status == 200) {
                # enable on callee's connection
                tcp_keepalive_enable("60", "5", "5");
                # enable on caller's connection
                tcp_keepalive_enable("$avp(caller_conid)", "60", "5", "2");
        }
        ...
}

3.4.  tcp_keepalive_disable([conid])

   Disables keepalive on a TCP connection.

   Meaning of the parameters is as follows:
     * conid (optional): the Kamailio internal connection id on which TCP
       keepalive will be disabled. If no parameter is given, the keepalive
       mechanism will be disabled on the current message source
       connection.

   Returns 1 on success, -1 on failure.

   Example 1.6. tcp_keepalive_disable usage
request_route {
        ...
        if (is_method("BYE")) {
                $avp(bye_conid) = $conid;
                t_on_reply("foo");
        }
        ...
}

onreply_route[foo] {
        ...
        if (is_method("BYE") && status == 200) {
                tcp_keepalive_disable();
                tcp_keepalive_disable("$avp(bye_conid)");
        }
        ...
}

3.5.  tcp_set_connection_lifetime([conid], lifetime)

   Sets the connection lifetime of a connection (TCP).

   Meaning of the parameters is as follows:
     * conid (optional): the Kamailio internal connection id on which to
       set the new lifetime. If no parameter is given, it will be set on
       the current message source connection.
     * lifetime (seconds): the new connection lifetime.

   Returns 1 on success, -1 on failure.

   Example 1.7. tcp_set_connection_lifetime usage
...
# use 10s as default lifetime
tcp_connection_lifetime=10
...

request_route {
        ...
        if (is_method("REGISTER") && pv_www_authenticate("$td", "xxx", "0")) {
                # raise the TCP lifetime to a bigger value
                tcp_set_connection_lifetime("3605");
        }
        ...
}

3.6.  tcp_enable_closed_event([conid])

   Explicitly enables the "tcp:closed" event route on a TCP connection.

   Meaning of the parameters is as follows:
     * conid (optional): the Kamailio internal connection id. If no
       parameter is given, it will be enabled on the current message
       source connection.

   Returns 1 on success, -1 on failure.

   Example 1.8. tcp_set_closed_event usage
...
# "tcp:closed" event route is "manual" mode
modparam("tcpops", "closed_event", 2)
...

request_route {
        ...
        if (is_method("REGISTER") && pv_www_authenticate("$td", "xxx", "0")) {
                # it will be called for this specific connection
                tcp_enable_closed_event();
        }
        ...

}

event_route[tcp:closed] {
        xlog("connection $conid was closed");
}

3.7.  tcp_get_conid(hostport, pvname)

   Get the connection id based on target host:port. The connection id is
   set in the variable named by pvname parameter.

   Meaning of the parameters is as follows:
     * hostport - target "host:port" address, the port can be omitted
       (default to 5060) and the parameter can contain variables.
     * pvname - target variable name.

   Return values:

   1: connection was found

   -1: connection was not found or an error occurred

   Example 1.9. tcp_get_conid usage
...
        if(tcp_get_conid("127.0.0.1:5060", "$var(conid)")) {
                xlog("connection id is: $var(conid)\n");
        }
...

3.8.  tcp_set_otcpid(conid)

   Set the value for outbound tcp connection id.

   Meaning of the parameters is as follows:
     * conid - the value of tcp connection id. It can be an integer number
       or a variable holding an interver value.

   Return values:
     * 1: success
     * -1: failure

   Example 1.10. tcp_set_otcpid usage
...
        $var(conid) = 10;
        tcp_set_otcpid("$var(conid)");
...

3.9.  tcp_set_otcpid_flag(mode)

   Set or reset the internal flag for using or not the outbound tcp
   connection id for sending out. The outbound connection id can be set by
   module or by config using tcp_set_otcpid(...) function. An example of a
   module setting the otcpid is register via lookup location function,
   which sets the filed to the connection id used to receive the
   registration request.

   Meaning of the parameters is as follows:
     * mode - if 0, then the flag is reset, otherwise it is set.

   Return values:
     * 1: success
     * -1: failure

   Note: if you set the flag to use the outbound tcp connection id, then
   custom config changes to the destination address, like updating the
   r-uri ($ru) or dst uri ($du) are not resetting it, so the same already
   set connection id is used and the SIP request might be sent to the
   unexpected destination. Reset the flag in such case, if you set it
   previously.

   Example 1.11. tcp_set_otcpid_flag usage
...
        $var(cmode) = 1;
        tcp_set_otcpid_flag("$var(cmode)");
...

3.10.  tcp_close_connection([conid])

   Trigger a close of the connection corresponding to current SIP message
   or to connection id 'conid'.

   Meaning of the parameters is as follows:
     * conid - the value of tcp connection id. It can be an integer number
       or a variable holding an interver value.

   Return values:
     * 1: success
     * -1 (or other negative values): failure

   Example 1.12. tcp_close_connection usage
...
        $var(conid) = 10;
        tcp_close_connection("$var(conid)");
...

4. Event routes

   4.1. tcp:closed
   4.2. tcp:timeout
   4.3. tcp:reset
   4.4. Example

   The 3 following routes are called when a socket is closed.

   The corresponding $conid , $Ri , $Rp , $si , $sp and $proto variable
   will be available in the event routes.

   Whether these routes are always called, never, or on a per socket basis
   is controlled by the closed_event parameter.

   Note that the event routes can be executed by TCP main process, which
   manages the TCP connections but does not hande the SIP traffic over
   them. It is very important not do do any time consuming operations
   inside the event routes. Also, many resources might not be available in
   the TCP main process (e.g., database connections), consider using async
   module with async_task_data(...) or async_task_group_data() functions
   for delegating task execution to async workers.

4.1.  tcp:closed

   Called for each "normal" TCP socket closure by the other side
   (FIN,ACK).

4.2.  tcp:timeout

   Called for connection timeouts (unanswered keepalives).

4.3.  tcp:reset

   Called if the connection is reset by peer (RST).

4.4.  Example

...
event_route[tcp:closed] {
        xlog("L_INFO", "$proto connection closed ($conid)\n");
}

event_route[tcp:timeout] {
        xlog("L_INFO", "$proto connection timed out ($conid)\n");
}

event_route[tcp:reset] {
        xlog("L_INFO", "$proto connection reset by peer ($conid)\n");
}
...
