TCP Ops module

Camille Oudot

Orange

Olle E. Johansson

Edvina AB

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])
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. 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
1.8. tcp_get_conid usage

Chapter 1. Admin Guide

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)

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

3. Functions

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

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

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

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

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

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.8. tcp_get_conid usage

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

4. Event routes

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