NAT Traversal Module

The nat_traversal module implements a very sophisticated keepalive mechanism, that is able to handle the most complex environments and use cases, including distributed environments with multiple proxies. Unlike existing keepalive solutions that only send keepalive messages to user agents that have registered (during their registration), the nat_traversal module can keepalive an user agent based on multiple conditions, making it not only more flexible and more efficient, but also able to work in environments and with use cases where a simple keepalive implementation based on keeping alive registrations alone cannot work.

The keepalive mechanism works by sending a SIP request to a user agent behind NAT to make that user agent send back a reply. The purpose is to have packets sent from inside the NAT to the proxy often enough to prevent the NAT box from timing out the connection. Many NAT boxes do not consider packets that travel from the outside to the inside of the NAT to reset the connection expiration timer, thus to keepalive a user agent we need to trigger an answer from it.

One of the major limitations of an implementation that only sends keepalive messages to registered user agents, is that it creates an artificial association between the concept of network visibility with the concept of user registration. The registration process only creates network visibility for incoming INVITE requests, in other words for incoming calls. However, there are other cases where a user agent needs to preserve its network visibility when behind NAT, that have nothing to do with receiving incoming calls. One of them is the ability of the user agent to keep receiving NOTIFY requests for a presence subscription it has made. Another situation is where the user agent should be able to receive all messages within a dialog it has initiated, even if it is not registered. In the first case, a presence agent is required to register to be able to receive notifications for its subscriptions and it has to keep the registration active the whole time. In the second case a user agent that wants to make an outgoing call has to register and keep the registration active during the call, otherwise it may not be able to receive future in-dialog messages, including the BYE that closes the dialog.

Not only we have this forced association shown above, that requires a user agent to register to be able to do anything, but a simple keepalive implementation based on sending keepalive messages only to registered user agents, will also fail to work in common cases, exactly because of this artificial association. For example lets assume that we have an user agent that is registered. If during an outgoing call initiated by this user agent, the agent stops registering, then it will not be able to receive further in-dialog messages after the NAT binding expires. The same is true for a presence agent, receiving notifications for its subscriptions.

In environments with multiple proxies handling the same domains, the problem gets even more acute. In this case the incoming and outgoing paths for a call may be completely different: the user agent may register using one proxy as an entry point to the network, but may make an outgoing call using a different proxy as the network entry point. Even more a registration may use a different proxy as the entry point to the network with each renewal of the registration, making it volatile and unreliable for anything else except incoming calls. A keepalive implementation that only sends keepalive messages to registered user agents will not be able to guarantee the delivery of in-dialog messages for outgoing calls even if it requires the user agent to register before making a call. In this case, even if we assume that the user agent would pick the same proxy for an outgoing call as the one it has used for the last registration, at the next registration it may pick another one (as returned by DNS), and will dissociate the incoming and outgoing paths rendering the outgoing path unusable (assuming the outgoing call takes longer than the registration period).

All this leads to the conclusion that a keepalive implementation based solely on sending keepalive messages to registered user agents can only work in single proxy environments and then only work reliably if it requires the user agent to register before doing anything else, even though some actions would not require a user agent to register.

To avoid the above mentioned issues, this implementation introduces the concept of network visibility for a given condition. This way we can keepalive a user agent for multiple independent conditions, thus avoiding all the problems presented above.

The conditions for which the module will send keepalive messages are:

A user agent's NAT entry point may be kept alive for one or multiple of the conditions listed above. Even when a NAT endpoint is kept alive for more than one condition, only one keepalive message is sent to that NAT endpoint. The presence of multiple conditions for a NAT endpoint, only guarantees that the network visibility for a user agent based on a certain condition will be available while that condition is true, independently of the other conditions. When all the conditions to keepalive a NAT endpoint will disappear, that endpoint will be removed from the list with the NAT endpoints that need to be kept alive.

The user interface for the keepalive functionality is very simple. It consists of a single function called nat_keepalive() that needs to be called only once for the requests that trigger the need for network visibility. These requests are: REGISTER, SUBSCRIBE and outgoing INVITEs. After such a request arrives it makes the user agent visible for the purpose of receiving back other messages. Thus, after a REGISTER the user agent may receive back incoming calls, after a SUBSCRIBE it may receive back notifications and after an outgoing INVITE it may receive back further in-dialog messages including the BYE that ends the dialog. The nat_keepalive() function needs to be called on the proxy that directly receives the request from the user agent, if it determines that the user agent making the request is behind NAT. The function needs to be called before the request gets either a stateless reply or it is relayed with t_relay(). Calling the nat_keepalive() function has no effect if the request gets no stateless reply or it is not relayed.

For environments with multiple proxies, where the proxy that acts as an entry point to the network for a given request is not the one that actually handles the request, then the nat_keepalive() function needs to be called on the proxy that is the entry point and after that the request must be sent to the proxy that actually handles the request using t_relay(). This is needed because the keepalive functionality detects from the stateless replies or the TM relayed replies if the NAT endpoint needs to be kept alive for the condition triggered by the request for which the nat_keepalive() function was called. For example assume a network where a proxy P1 receives a REGISTER from an user agent behind NAT. P1 will determine that the user agent is behind NAT so it needs keepalive functionality, but another proxy called P2 is actually handling the subscriber registrations. In this case P1 has to call nat_keepalive() even though it doesn't yet know the answer P2 will give to the REGISTER request (which may even be a negative reply) or if P2 will restrict the proposed expiration time in any way. Thus P1 calls nat_keepalive() after which it calls t_relay(). When the reply from P2 arrives, a callback is triggered which will determine if the request did get a positive reply, and if so it will extract the registration expiration time and enable the keepalive functionality for that endpoint for the registration condition for the time given by the registration expiration. For single proxy environments, or if P1 is the same as P2, then t_relay() is not called, instead save_location() is called if the registration is accepted. Then the same process described above happens only this time triggered by a stateless reply callback. In both cases, calling nat_keepalive() when the REGISTER is received has no other effect that to trigger some callbacks that will determine from the reply if the caller endpoint should be kept alive or not.

Below is described how nat_keepalive() should be called and what it does for each of the requests that need keepalive functionality (the function should only be called if it is determined that the user agent that generated the request is behind NAT):

Considering the elements presented in this section, we can say that the nat_traversal module provides a flexible and efficient keepalive functionality that is very easy to use. Because only the border proxies send keepalive messages, the network traffic is minimized. For the same reason, message processing in the proxies is also minimized, as border proxies generate keepalive messages themselves and send them stateless, instead of having to relay messages generated by the registrars. Network traffic is also minimized by only sending a single keepalive message for an endpoint no matter for how many reasons the endpoint is kept alive. Keepalive messages are also distributed over the keepalive interval to avoid overloading the proxy by generating too many messages at a time. The nat_traversal module keeps its internal state about endpoints that need keepalive, state that is build while messages are processed by the proxy and thus it doesn't need to transfer any information from the usrloc module, which should also improve its efficiency.

The following modules must be loaded before this module:

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

The time interval (in seconds) required to send a keepalive message to all the endpoints that need being kept alive. During this interval, each endpoint will receive exactly one keepalive message. A negative value or zero will disable the keepalive functionality.

Default value is “60”.

...
modparam("nat_traversal", "keepalive_interval", 90)
...
        

What SIP method to use to send keepalive messages. Typical methods used for this purpose are NOTIFY and OPTIONS. NOTIFY generates smaller replies from user agents, but they are almost entirely negative replies. Apparently almost none of the user agents understand that the purpose of the NOTIFY with a “keep-alive” event is to keep NAT open, even though many user agents send such NOTIFY requests themselves. However this does not affect the result at all, since the purpose is to trigger a response from the user agent behind NAT, positive or negative replies having little relevance as they are discarded anyway. The OPTIONS method on the other hand has a much higher rate of positive replies, but at the same time those positive replies are much bigger, mostly because the OPTIONS method is used to inform about the user agent capabilities and thus it includes a lot of extra headers to indicate those capabilities. Many user agents also include a SDP body with a bogus media session, probably to indicate media capabilities. All of this makes that positive replies to OPTIONS requests are 2 to 3 times bigger than negative replies or replies to NOTIFY requests. For this reason the default value for the used method is NOTIFY.

Default value is “NOTIFY”.

...
modparam("nat_traversal", "keepalive_method", "OPTIONS")
...
        

Indicates what SIP URI to use in the From header of the keepalive requests. If not specified it will use sip:keepalive@proxy_ip, where proxy_ip is the IP address of the outgoing interface used to send the keepalive message, which is the same interface on which the request that triggered keepalive functionality arrived.

Default value is “sip:keepalive@proxy_ip” with proxy_ip being the actual IP of the outgoing interface.

...
modparam("nat_traversal", "keepalive_from", "sip:keepalive@my-domain.com")
...
        

Specifies extra headers that should be added to the keepalive messages that are sent by the proxy. The header specification must also include the CRLF (\r\n) line separator. Multiple headers can be specified by concatenating them and each of them must include the \r\n separator.

Default value is undefined (send no extra headers).

...
modparam("nat_traversal", "keepalive_extra_headers", "User-Agent: OpenSIPS\r\nX-MyHeader: some_value\r\n")
...
        

Specifies a filename where information about the NAT endpoints and the conditions for which they are being kept alive is saved when OpenSIPS exits. The information in this file is then used when OpenSIPS starts to restore its internal state and continue to send keepalive messages to the NAT endpoints that have not expired in the meantime. This is useful when restarting OpenSIPS to avoid losing keepalive state information about the NAT endpoints. The internal keepalive state is guaranteed to be saved in this file on exit, even when OpenSIPS crashes.

The value of this parameter can be either a relative path, in which case it will store it in the OpenSIPS working directory, or an absolute path.

Default value is undefined “keepalive_state”.

...
modparam("nat_traversal", "keepalive_state_file", "/run/opensips/keepalive_state")
...
        

The ID of the cluster the module is part of. The clustering support is used by the nat_traversal module for controlling the pinging process. When part of a cluster of multiple nodes, the nodes can agree upon which node is the one responsible for pinging.

The clustering with sharing tag support may be used to control which node in the cluster will perform the pinging/probing to the contacts. See the cluster_sharing_tag option.

For more info on how to define and populate a cluster (with OpenSIPS nodes) see the "clusterer" module.

Default value is “0 (none)”.

...
# Be part of cluster ID 9
modparam("nat_traversal", "cluster_id", 9)
...

The name of the sharing tag (as defined per clusterer modules) to control which node is responsible for perform pinging of the contacts. If defined, only the node with active status of this tag will perform the pinging.

The cluster_id must be defined for this option to work.

This is an optional parameter. If not set, all the nodes in the cluster will individually do the pinging.

Default value is “empty (none)”.

...
# only the node with the active "vip" sharing tag will perform pinging
modparam("nat_traversal", "cluster_id", 9)
modparam("nat_traversal", "cluster_sharing_tag", "vip")
...

Check if the client is behind NAT. What tests are performed is specified by the type parameter which is an integer given by the sum of the numbers corresponding to the tests that one wishes to perform. The numbers corresponding to individual tests are shown below:

For example calling client_nat_test(3) will perform test 1 and test 2 and return true if at least one succeeds, otherwise false.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
if (client_nat_test(3)) {
    .....
}
...
        

Will replace the IP and port in the Contact header with the IP and port the SIP message was received from. Usually called after a successful call to client_nat_test(type)

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE.

...
if (client_nat_test(3)) {
    fix_contact();
}
...
        

Trigger keepalive functionality for the source address of the request. When called it only sets some internal flags, which will trigger later the addition of the endpoint to the keepalive list if a positive reply is generated/received (for REGISTER and SUBSCRIBE) or when the dialog is started/replied (for INVITEs). For this reason, it can be called early or late in the script. The only condition is to call it before replying to the request or before sending it to another proxy. If the request needs to be sent to another proxy, t_relay() must be used to be able to intercept replies via TM or dialog callbacks. If stateless forwarding is used, the keepalive functionality will not work. Also for outgoing INVITEs, record_route() should also be used to make sure the proxy that keeps the caller endpoint alive stays in the path. For multi-proxy setups, this function should always be called on the border proxies (the ones that received the request directly from the user agent). For more details about this function, see the Implementation subsection from the Keepalive functionality section.

This function can be used from REQUEST_ROUTE.

...
if (($rm=="REGISTER" || $rm=="SUBSCRIBE" ||
    ($rm=="INVITE" && !has_totag())) && client_nat_test(3))
{
    nat_keepalive();
}
...
        

Indicates the total number of NAT endpoints that are being kept alive.

Indicates how many of the NAT endpoints are kept alive for registrations.

Indicates how many of the NAT endpoints are kept alive for subscriptions.

Indicates how many of the NAT endpoints are kept alive for taking part in an INVITE dialog.

Returns the local socket used to send messages to the given NAT endpoint URI. The socket has the form proto:ip:port. The NAT endpoint URI is in the form: sip:ip:port[;transport=xxx] with transport missing if UDP. If the requested NAT endpoint URI is present in the internal keepalive table for any condition, it will return its associated local socket, else it will return null. The nat_endpoint can be a string or another pseudo-variable.

This can be useful to restore the sending socket when relaying messages to a given user agent in multi-proxy environments. Consider an example where 2 proxies are involved, P1 and P2. A user agent registers by sending a REGISTER request to P1. P1 will call nat_keepalive() but because it determines that P2 should actually handle the user registration will forward the request to P2. Now assume P2 receives an incoming INVITE for this user. It will determine that the registration came through P1 and will forward the request to P1. P2 should also include the NAT endpoint URI where this request is to be relayed. This information should have been provided by P1 when it relayed the REGISTER request to P2. The means to do this is out of the scope of this example, but one can either use the path extension or custom headers to do this. When P1 receives the INVITE it will use the NAT endpoint URI it has received along with the request to determine the socket to send out the request, which should be the same as the one where the registration request was originally received. In the example below lets assume that P2 provided the original NAT endpoint address in a custom header called X-NAT-URI and that it also provides a custom header called X-Scope to indicate that the message is sent to P1 for being relayed back to the user agent by P1 which has the NAT open with it.

...
# This code runs on P1 which has received an INVITE from P2 to forward
# it to the user agent behind NAT (because P1 has the NAT open with it).
if ($rm=="INVITE" && $hdr(X-Scope)=="nat-relay") {
    $du = $hdr(X-NAT-URI);
    $fs = $keepalive.socket($du);
    t_relay();
    exit;
}
...
        

Returns the URI specification from where a request was received in the form sip:ip:port[;transport=xxx] with transport missing if UDP.

This pseudo-variable can be used to set the received AVP for the registrar module to indicate that a user agent is behind NAT. This is meant as a more flexible replacement for the fix_nated_register() function, because it allows one to modify the source uri by appending some extra parameters before saving it to the received AVP.

Another use for this pseudo-variable is in multi-proxy environments to indicate the NAT endpoint URI to the next proxy (if needed). Consider the previous example with two proxies P1 and P2. P1 receives the REGISTER request from a user agent and forwards it to P2 which does the actual registration. P1 needs to indicate the NAT endpoint URI to P2, so that P2 can include it later for incoming INVITE requests to this user agent.

...
modparam("registrar", "received_avp", "$avp(received_uri)")
modparam("registrar", "tcp_persistent_flag", 10)
...
# This code runs on the registrar, assuming it has received the
# REGISTER request directly from the user agent.
if ($rm=="REGISTER") {
    if (client_nat_test(3)) {
        if ($socket_in(proto)==UDP) {
            nat_keepalive();
        } else {
            # Keep TCP/TLS connections open until the registration
            # expires, by setting the tcp_persistent_flag
            setflag(10);
        }
        force_rport();
        $avp(received_uri) = $source_uri;
        # or we could add some extra parameters to it if needed
        # $avp(received_uri) = $source_uri + ";relayed=false" 
    }
    if (!www_authorize("", "subscriber")) {
        www_challenge("", "0");
        return;
    } else if ($au!=$tU) {
        sl_send_reply("403", "Username!=To not allowed ($au!=$tU)");
        return;
    }

    if (!save("location")) {
        sl_reply_error();
    }
    exit;
}
...
        

...
# This code runs on P1 which received the REGISTER request and has to
# forward it to the registrar P2.
if ($rm=="REGISTER") {
    if (client_nat_test(3)) {
        force_rport();
        nat_keepalive();
        append_hf("X-NAT-URI: $source_uri\r\n");
    }
    $du = "sip:P2_ip:P2_port";
    t_relay();
    exit;
}
...
        

Returns a boolean value (0 or 1) indicating if dialog tracking will be enabled by the nat_traversal module. The nat_traversal module will always track the dialog (by calling create_dialog internally) unless told otherwise.

This is an advanced setting which is only meant to be used by multi-proxy setups where a proxy doesn't want to keep track of a dialog, that is, if it won't stay in the signaling path.

By setting this pv to 0 the nat_traversal module will not attempt to create the dialog.

In this case the usage is straight forward. The nat_keepalive() function needs to be called before save_location() for REGISTER requests, before handle_subscribe() for SUBSCRIBE requests and before t_relay() for the first INVITE of a dialog.

If the proxy receiving the REGISTER request is the same as the proxy handling it, then the case is reduced to the single proxy case. For this example, lets assume they are different. We have a user agent UA1 for which the registration is handled by the proxy P1. However UA1 sends the REGISTER to P0 which in turn forwards it to P1 like this: UA1 --> P0 --> P1. In this case P0 calls nat_keepalive(), adds the NAT endpoint URI to the request (for example using a custom header) and forwards the request to P1. P1 will save the user in the user location together with the NAT endpoint URI.

When an incoming INVITE request arrives on P1 for UA1, P1, will lookup the location and determine that it has to relay it to P0 because P0 has the NAT open with UA1. P1 will include the original NAT endpoint URI in the request and an indication that the only role P0 has in this transaction is to relay it to UA1. P0 will receive this request and determine that is has to act as a relay for it. It will extract the NAT endpoint URI, then based on it the corresponding local socket using $keepalive.socket(endpoint_uri). It will then set both $du and $fs to the values it has found, call record_route() to stay in the path and call t_relay() to send it to UA1.

Handling other type of requests (like for example SUBSCRIBE or MESSAGE) that arrive on P1 for UA1 is done the same way as with the first INVITE, on both P1 and P0.

If the proxy receiving the SUBSCRIBE request is the same as the proxy handling it, then the case is reduced to the single proxy case. For this example, lets assume they are different. We have a user agent UA1 for which subscriptions are handled by the proxy P1. However UA1 sends the SUBSCRIBE to P0 which in turn forwards it to P1 like this: UA1 --> P0 --> P1. In this case P0 calls nat_keepalive(), then calls record_route() to stay in the path and forwards the request to P1 using t_relay(). Further SUBSCRIBE and NOTIFY requests will follow the record route and use P0 as a NAT entry point to have access to UA1. Further in-dialog SUBSCRIBE requests should also call record_route().

If the proxy receiving the INVITE request is the same as the proxy handling it, then the case is reduced to the single proxy case. For this example, lets assume they are different. We have a user agent UA1 which is handled by the proxy P1 and UA2 which is handled by P2. UA2 has registered with P2 going through P3, while UA1 calls UA2 by sending the first INVITE to P0. The call flow for the first INVITE looks like this: UA1 --> P0 --> P1 --> P2 --> P3 --> UA2. In this case P0 calls nat_keepalive(), then calls record_route() to stay in the path and forwards the request to P1. P1 authenticates UA1 then forwards the request to P2, which is the home proxy for UA2. P1 doesn't have to use record_route to stay in the path, but it can do that if needed for other purposes. P2 will lookup UA2 and find out that it is reachable through P3. It will take the original NAT endpoint URI that is has saved in the user location when UA2 has registered and include it in the message along with an indication that P3 only has to relay the message to UA2. If P2 does accounting or starts a media relay, it should also call record_route() to stay in the path. Then it forwards the request to P3 using t_relay(). P3 will detect that it only has to relay the request to UA2 because it has the NAT open with it. It will extract the NAT endpoint URI from the message and the local sending socket using $keepalive.socket(endpoint_uri) and will set both $du and $fs. After that it will call record_route() to stay in the path, and forward the request to UA2 using t_relay(). Further in-dialog requests will follow the recorded route and use P0 and P3 as access points to UA1 respectively UA2. All the proxies that have used record_route() during the first INVITE should also call record_route() during further in-dialog requests to keep staying in the path.