mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
307 lines
7.9 KiB
307 lines
7.9 KiB
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");
|
|
}
|
|
...
|