Up until now we have run SER as a foreground process. From this point forward we will run SER as a daemon. The fork directive tells the SER daemon to run in the background. This is a requirement for using the init.d start script shown in the appendix.

Since we are running SER as a background process we must set the log_stderror directive equal to no in order to not keep SER in the foreground.

The uri module is introduced here to access the has_totag() function. This function is necessary for processing re-INVITEs and is describe below.

The domain module is needed because the mediaproxy module has dependencies to it for the is_uri_host_local() and is_from_local() functions.

Here we introduce the use of mediaproxy. This line has confused many SER novices because it implies that mediaproxy is included with SER, however, mediaproxy is an external application. This line only invokes the mediaproxy module, which is the glue between SER and the actual mediaproxy application.

We use some of the nathelper library functions to determine whether or not a SIP UA is NATed. An important item to understand is that just because nathelper is included here does not indicate that we are using rtpproxy (another RTP proxy application comparable to mediaproxy). Also note here that nathelper is generally referred to in the same context as rtpproxy because most people that use rtpproxy also use nathelper.

The textops module provide utility functions for manipulating text, searching for substrings, and checking for the existence of specific header fields.

Since we are using mediaproxy rather than rtpproxy, we need to tell the nathelper module to not attempt to bind to a running instance of rtpproxy. If we were to omit this line then syslog would contain many errors stating that rtpproxy could not be found.

Our NAT traversal is using mediaproxy, and therefore we have decided to use the mediaproxy keep-alive mechanism, which will ping NATed SIP clients on a regular basis. Because of this we need to disable the rtpproxy ping mechanism since we do not need it.

The mediaproxy natping_interval is a very crucial setting, which controls how often our SER proxy will ping registered SIP clients. Most NAT devices will only hold port bindings open for a minute or two, so we specify 30 seconds here.

This causes SER to send a 4-byte UDP packet to each SIP client every 30 seconds. This is all that is required to keep NATed clients alive.

NOTE: Some NAT devices have been reported to not allow incoming keep-alives. Thus, many user clients have their own implementations of keep-alive. If you experience one-way audio problems after a while, you may have run into this problem. The only solution is to turn on user client keep-alives. Also, keep in mind that it is perfectly acceptable to have the SER proxy send keep-alive traffic as well as the SIP traffic to the client.

SER and the mediaproxy dispatcher communicate via a standard Unix socket, which is specified here.

Mediaproxy may need to know when a SIP UA is asymmetric with respect to its SIP messaging port. Most SIP UAs are symmetric, meaning that they listen for incoming SIP messages on the same port as they use for sending their own SIP messages. However, if you find asymmetric clients that are not handled correctly, you can specify their User-Agent headers in this file.

A default example of this file can be found in the SER distribution under <ser-sources>/modules/mediaproxy/config/sip-asymmetric-clients. This example file has been copied and renamed to the path specified on this line.

Mediaproxy may need to know when a SIP UA is asymmetric with respect to its RTP port. If you find asymmetric clients that not handled correctly you can specify their User-Agent headers in this file.

A default example of this file can be found in the SER distribution under <ser-sources>/modules/mediaproxy/config/rtp-asymmetric-clients. This example file has been copied and renamed to the path specified on this line.

When SIP clients attempt to REGISTER with our SIP proxy we need a way to tell the registrar module to store NAT information for any particular UA. We do this by using flag 6, which has been arbitrarily chosen (but defined earlier in the loadmodule parameter section). We could have specified another integer here, but flag 6 seems to be the accepted standard for nat_flag.

If the nat_flag is set before calling the save() function to store contact information, SER will preserve the NAT contact information as well as set the flags column in the MySQL location table. By doing so, we can call lookup(location) when processing messages and flag 6 will be set for NATed clients.

If the received message is an INVITE and it is from a SIP client that is behind a NAT we need to embed a special NAT flag, which will be returned to our SIP proxy in the case of a re-INVITE. This embedded flag can then be located in our loose route processing logic to determine if the message originator is NATed or not.

If the message originator is NATed we specify the Record-Route header explicitly by using the record_route_preset() function. We pass to this function the IP address of our SIP proxy. If your SIP proxy sits behind a router that has Application Level Gateway (ALG) support, such as a Cisco 3600 series, then you will use the physical RFC1918 address of your SIP proxy here because the ALG-enabled router will rewrite private IP addresses.

NOTE: For those that are familiar with rtpproxy you may be wondering why this step is necessary since rtpproxy doesnt require the embedded ;nat=yes tag. The reason mediaproxy requires this and rtpproxy does not is that the use_media_proxy() function, which is introduced later in this example, will set up a new RTP proxy channel if you call the function and the <Call-ID> header is not found it mediaproxys list of active sessions.

The corresponding function in rtpproxy has the ability to instruct rtpproxy to only take action if a previous <Call-ID> header is found in the list of active rtpproxy sessions.

This difference also affects the loose_route() code block because mediaproxy users must look for the ;nat=yes tag when processing re-INVITE messages and rtpproxy users do not. So from this aspect, rtpproxy is somewhat easier to use.

If the message is not an INVITE from a NATed SIP client and it is not a REGISTER then we just call record_route() as normal to ensure that messages return to our SIP proxy from upstream or downstream SIP proxy servers or PSTN gateways.

Anytime we receive a BYE or CANCEL message we should assume that it is for a call that has been set up with mediaproxy. So here we just attempt to tear down the RTP proxy session. It is perfectly safe to call end_media_session(), even for calls that were not RTP proxied.

Tell mediaproxy to end the session for the current call.

Our NAT traversal requirements must handle re-INVITE messages in a special manner to prevent RTP media streams from dropping off during a re-INVITE. So we do special re-INVITE NAT processing here.

In order to ensure that we are dealing only with an actual re-INVITE, we must make sure the has_totag() function returns TRUE and loose_route() is also TRUE. The reason for this is that it is possible for an original INVITE message to include predefined route headers, which would cause loose_route() to return TRUE. Therefore the has_totag() is checked because only connected calls will have a tag= entry in the <To> header (ie, calls where a 200 OK as been generated by the callee).

In other words this new security check is based on the fact that established SIP dialogs will have a "totag" whereas calls in the process of being established will not. To ensure that our loose routing logic is not exposed to malicious users we make sure that INVITE and REFER messages are only accepted for established dialogs.

If the message is an INVITE then we need to challenge the message sender for credentials. If the message sender cannot provide valid credentials then SER will reply with a 403 error message.

NOTE: This current example requires that the caller and callee are registered with the SIP router. Future examples will expand on this section to allow "trusted" SIP devices, such as a PSTN gateway.

Now we check the NAT status of the re-INVITE to see if the message originator is NATed or not by calling client_nat_test("3"). We also search for a <Route> header that contains the ";nat=yes" embedded tag which would have been included by our record_route_preset() discussed earlier. If the ;nat=yes tag is found, then the caller is NATed.

If the message sender is NATed or the re-INVITE contains the ;nat=yes flag, we set flag 6 for later reference. This flag can then be checked in the reply_route.

In order to proxy RTP streams we just call use_media_proxy(). This will communicate to the external mediaproxy server causing it to open UDP ports for both clients, or maintain an existing RTP proxy session for an existing call, based on the <Call-ID> header. Calling use_media_proxy() causes the SDP payload to be rewritten with the IP address of the mediaproxy server and the allocated ports.

In the event that our message is no longer to be handled by our SIP router, we call our NAT handling route block to enable mediaproxy if needed before sending the message to its destination.

We now explicitly handle CANCEL messages. CANCEL messages can be safely processed with a simple call to t_relay() because SER will automatically match the CANCEL message to the original INVITE message. So here we just route the message to the default message handler.

Enable mediaproxy if needed before sending the message to its destination.

When dealing with NATed clients we must correctly handle response messages that may be heading back to the client. These response messages are accessible in SER by using a reply_route block.

SER allows you to specify multiple reply_route blocks which can perform many tasks. Here we specify that any reply messages must be passed to reply_route[1] which is defined at the end of the ser.cfg file.

In order to invoke a reply_route, you simply need to set the handler prior to calling t_relay(), as we have done here.

If the message could not be sent and it is an INVITE or ACK then we should attempt to release any previously established mediaproxy session.

If client_nat_test() returns true then we must set flag 6 to inform the registrar module that the client is NATed.

Also note that we must only invoke client_nat_test() if the SIP message being processed contains an actual <Contact:> header. Otherwise an error will be written to syslog.

NOTE: An interesting side note here is that the regular expression for the <Contact:> header is ^Contact:[ ]*\* which reads like this;

If the line starts with the text Contact: and is followed by any number of spaces (ie: [ ]*) and then followed by an asterisk (ie: \*). The reason for this is that a SIP client can include the header <Contact: *> just the same as <Contact:'space'*> and both are valid. By testing for one or more white space characters we catch all formatting styles.

NOTE: The Contact: header will contain an asterisk "*" character when a SIP client is requesting to be "unregistered" from the SIP proxy. In fact, many SIP clients can and/or will send a REGISTER message with a "Contact: *" header when they are rebooted.

If a client is indeed NATed, then we must inform the SER registrar module that it needs to store the actual IP address and port that the SIP message came from. This information is then used by subsequent calls to lookup(location) in order to find the public IP address of a SIP client that is behind a NAT device.

Fix_nated_register() is used specifically for processing REGISTER messages from NATed clients. This is very different from fix_nated_contact() because the former will not alter the URI in the <Contact:> header whereas the latter will.

Fix_nated_register() will only append parameters to the <Contact:> header URI, which follows RFC3261 Section 10.3 on handling REGISTER messages. If we had used fix_nated_contact() here then you will likely have compatibility problems where SIP UAs do not honor the 200 OK response that SER replies with upon successful REGISTRATION. This would then cause the SIP client to loose its registration.

Force_rport() adds the received IP port to the top most via header in the SIP message. This enables subsequent SIP messages to return to the proper port later on in a SIP transaction.

Invite messages have slightly different NAT testing requirements than REGISTER messages. Here we only test to see if the SIP message has an RFC1918 IP address in the <Contact:> header and whether or not the SIP UA contacted SER on a different IP address or port from what is specified in the via header.

If it is determined that the SIP client is NATed, then we set flag 7 for later reference.

NOTE: This client_nat_test() only determines if the message sender is behind a NAT device. At this point in the ser.cfg file we have not determined if the message recipient is NATed or not.

Add the received port to the VIA header.

Now we rewrite the messages <Contact:> header to contain the IP address and port of the public side of the NATed SIP client.

Enable mediaproxy if needed before sending the message to its destination.

Now we find the contact record for the party being called.

NOTE: A subtle, but very important, detail here is that flag 6 will be set by the call to lookup(location) in route[2] if the party being called is found in the MySQL location table and is NATed. The reason flag 6 will be set is because we specified this as the registrar modules nat_flag parameter.

Enable mediaproxy if needed before sending the message to its destination.

Now that we have taken care of all the NAT related items, we can safely send the INVITE message to its destination.

Route[4] is a convenience route block which enabled mediaproxy if either the message sender (flag 7) or the message recipient (flag 6) are NATed.

Flag 8 is used to make sure the mediaproxy doesn't get invoked more than once for our call. If mediaproxy were to erroneously be called more than once then the SIP message would end up with a corrupted SDP payload because the call to use_media_proxy() would alter the message incorrectly.

If flag 8 is not set then set it to prevent calling route[4] again.

Here we introduce a reply_route handler. A reply_route is defined just like any other block in SER. The only difference is that it is called onreply_route.

Any message that is passed to this block will be returning to the original sender. You can think of these messages as the response to the original request that the caller made. The types of messages that will appear here will have an integer response code, much like HTTP response codes. Examples here would be 200, 401, 403, and 404.

In this ser.cfg we are only interested in response codes of 180, 183, and all 2xx messages for NATed clients. We can check the status as shown with a regular expression. If any of these response codes are found then this statement will be TRUE.

An important thing to note is that we can check flags set in the other route blocks because their scope is still valid. So our caller and callee NAT flags are still accessible. If flag 6 is set then the caller is NATed, and if flag 7 is set then the callee is NATed.

We can only call use_media_proxy() for SIP messages that have a valid <Contact> parameter in the SDP payload. So here we test to make sure the c= parameter is valid by simply checking the SDP payload length. We assume that if we have an SDP payload then we will have a c= parameter and can call use_media_proxy().

If we were to simply call use_media_proxy() then we would likely see errors in syslog.

Finally we rewrite the messages <Contact:> header to contain the IP address and port of the public side of the NATed SIP client.