Table of Contents
List of Examples
Table of Contents
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).
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).
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.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");
}
...
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.3. tcp_conid_state usage
...
if(!tcp_conid_state("$var(conid)")) {
xlog("L_ERR", "Connection $conid is closed or malfunctional\n");
}
...
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.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");
}
...
}
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.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)");
}
...
}
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.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");
}
...
}
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.
Returns 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");
}
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.