kamailio/modules/tcpops

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)

        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])

        4. Event routes

              4.1. tcp:closed

   List of Examples

   1.1. Set closed_event parameter
   1.2. tcp_conid_alive usage
   1.3. tcp_conid_state usage
   1.4. tcp_keepalive_enable usage
   1.5. tcp_keepalive_disable usage
   1.6. tcp_set_connection_lifetime usage
   1.7. tcp_set_closed_event usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Parameters

        2.1. closed_event (int)

   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])

   4. Event routes

        4.1. tcp:closed

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.1. closed_event (int)

   If set to 0 (gloabbly 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)
...

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.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).

   Retuns values:

   1: Connection is OK

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

   Example 1.2. 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).

   Retuns 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 occured. Connection will likely close.

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

   Example 1.3. 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 reseting the
       connection.
     * interval (seconds): time between two keepalive probes.

   Retuns 1 on success, -1 on failure.

   Example 1.4. 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.

   Retuns 1 on success, -1 on failure.

   Example 1.5. 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.

   Retuns 1 on success, -1 on failure.

   Example 1.6. 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 (optionnal): the kamailio internal connection id. If no
       parameter is given, it will be enabled on the current message
       source connection.

   Retuns 1 on success, -1 on failure.

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

4. Event routes

   4.1. tcp:closed

4.1.  tcp:closed

   This route is called when a socket is closed by the remote party, or
   reset, or timeout. The corresponding $conid variable will be available
   in the event route.

   Whether this route is always called, never, or on a per socket basis is
   controlled by the closed_event parameter.

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