name mode size
..
doc 040000
Makefile 100644 231B
README 100644 9.56kB
tcpops.c 100644 6.2kB
tcpops.h 100644 1.42kB
tcpops_mod.c 100644 17.25kB
README
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]) 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 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]) 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.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) 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.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 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"); } ...