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)

        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

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)

   4. Event routes

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

1. Overview

   This modules 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("===== evapi 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.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");
        }
...

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.

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");
}
...
