Mediaproxy Module

Dan Pascu

Edited by

Dan Pascu

   Copyright  2004 Dan Pascu
     _________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview
        1.2. Principle of operation
        1.3. Types of SIP clients
        1.4. Features
        1.5. Exported parameters

              1.5.1. mediaproxy_socket (string)
              1.5.2. sip_asymmetrics (string)
              1.5.3. rtp_asymmetrics (string)
              1.5.4. natping_interval (integer)

        1.6. Exported Functions

              1.6.1. client_nat_test(type)
              1.6.2. fix_contact()
              1.6.3. use_media_proxy()
              1.6.4. end_media_session()

        1.7. Comparison with the nathelper module
        1.8. How to use sip_ping from the nathelper module

   2. Developer's Guide
   3. Frequently Asked Questions

   List of Examples
   1-1. Setting mediaproxy_socket parameter
   1-2. Setting sip_asymmetrics parameter
   1-3. Setting rtp_asymmetrics parameter
   1-4. Setting natping_interval parameter
   1-5. client_nat_test usage
   1-6. fix_contact usage
   1-7. use_media_proxy usage
   1-8. end_media_session usage
   1-9. Pinging exmaple configuration
     _________________________________________________________

Chapter 1. User's Guide

1.1. Overview

   Mediaproxy is a OpenSER module that is designed to allow
   automatic NAT traversal for the majority of existing SIP
   clients. This means that there will be no need to configure
   anything in particular on the NAT box to allow these clients
   to work behind NAT when using the mediaproxy module.
     _________________________________________________________

1.2. Principle of operation

   This NAT traversal solution operates by placing a mediaproxy
   server in the middle between 2 SIP user-agents. It mangles the
   SDP messages for both of them in a way that will make the
   parties talk with mediaproxy while they think they talk
   directly with each other.

   To achieve this, mediaproxy is actually composed by 2
   components:

     * the OpenSER mediaproxy module itself
     * an external proxy server called OpenSER MediaProxy
       (available from http://mediaproxy.ag-projects.com/ )

   To avoid confusion in this document the mediaproxy module will
   be called 'module' or 'mediaproxy module', while the
   mediaproxy server will be called 'proxy server' from here on.

   The proxy server can be run on the same machine as the module
   or on a remote host. Moreover it is possible for a single
   module to control multiple proxy servers running on multiple
   geographically distributed hosts. To find out more about the
   architecture of OpenSER MediaProxy please read the
   documentation that comes with it.

   To be able to act as a proxy between the 2 talking parties,
   the machine(s) running the module/proxy server must have a
   public IP address.

   The module will ask the proxy server to allocate as many
   sockets as there are media streams in the SDP body of the SIP
   INVITE/Ok messages. The proxy server will send back to the
   module the address and port(s) for them. Then the module will
   replace the original contact IP and RTP ports from the SDP
   messages with the ones provided by the proxy server. By doing
   this both clients will try to contact the proxy server instead
   of talking directly with each other. Once the clients contact
   the proxy server, it will record the addresses they came from
   and will know where to forward packets received from the other
   party This is needed because the address/port the NAT box will
   allocate for the leaving streams is not known before they
   actually leave the NAT box. However the address of the proxy
   server is always known (being a public one) so the 2 parties
   know where to connect and then after they did so, the proxy
   learns the addresses they came from and can forward packets
   between them.
     _________________________________________________________

1.3. Types of SIP clients

   The SIP clients that will work transparently behind NAT when
   using the mediaproxy module are the so-called symmetric
   clients. The symmetric clients have the particularity that use
   the same port to send the data as the one they use to receive
   it. In other words, if they are for example configured to use
   port 5060 for SIP signaling, they will use the same port when
   sending data as well as when receiving it. This must be true
   for both the SIP signaling as well as the RTP streams for a
   client to work transparently with the mediaproxy module
   without any additional configuration on the NAT box.

   This ability is important because the only way to get back to
   a client behind NAT is to send to the IP address and port the
   packet was received from. Once a packet is sent from the
   client behind NAT to the outside world, it opens a
   communication channel in the NAT box that is open in both
   directions for a while (it will timeout after a while after no
   more data is sent through it, but it can be kept active by
   sending data through it at certain regular time intervals).
   While this channel is open, any data sent to the public
   address and port that the NAT box assigned for the address and
   port the client behind NAT is sending from (and this mapping
   is guaranteed to be unique), will go back straight to the
   address and port the client has sent from. This is why is
   necessary for the clients to be symmetric. If they listen on
   the same port they sent from, the data sent back to the public
   address that the NAT box assigned to the leaving packets will
   actually reach the listening port of the client behind NAT.

   Some SIP clients implement particular algorithms to detect if
   they are actually behind a NAT box and try to act smart by
   detecting the IP address of the NAT box (or simply allowing
   one to manually configure it), and then use this IP address in
   the SIP and SDP messages instead of their own private IP
   address. This situation can be confusing for a module that
   tries to perform transparent NAT traversal as it can wrongly
   mistake such a client that is behind NAT with a client that is
   actually in the public address space. However for the
   mediaproxy module it is not important if the clients apply or
   not this kind of behavior, as it is able to cope with both
   situations gracefully.

   This doesn't mean that mediaproxy is not able to work with
   asymmetric clients behind NAT, but in their case special
   static forwarding routes need to be configured on the NAT box.

   Mediaproxy has special support for asymmetric clients, can
   detect them and send the data to the ports they expect it to,
   however they can work behind NAT only if static routes are
   configured on the NAT box since there is no way of getting
   back to an address/port that has not previously opened a data
   channel in the NAT box by sending something out first.
   Nevertheless the support for asymmetric clients is important,
   because without it they won't be able to work even when they
   have public Internet addresses. Also this support allows one
   to use an asymmetric client behind NAT if he can configure the
   NAT box to forward the packets meant to that client.

   The only requirement a symmetric SIP client must met to be
   able to work transparently behind NAT when using the
   mediaproxy module is to accept to be configured to use a so
   called outbound proxy and this proxy must be the one running
   with the mediaproxy module loaded.
     _________________________________________________________

1.4. Features

     * make symmetric clients work behind NAT transparently if
       they use the SIP server as the outbound SIP server.
     * handle all media streams specified in the SDP body. There
       is a limit of 64 RTP streams per session in the code now,
       but we hardly find this to be a limitation for the time
       being.
     * able to distribute RTP traffic load on multiple proxy
       servers running on multiple hosts.
     * able to specify which proxy server to use based on the SIP
       domain of the caller/destination (done by the proxy
       server's dispatcher module).
     * handle asymmetric clients properly. They can even work
       behind NAT if a proper port forwarding is done for them on
       the NAT box.
     _________________________________________________________

1.5. Exported parameters

1.5.1. mediaproxy_socket (string)

   It is the path to the filesystem socket where the proxy server
   listens for commands from the module.

   Default value is "/var/run/proxydispatcher.sock". 

   Example 1-1. Setting mediaproxy_socket parameter
...
modparam("mediaproxy", "mediaproxy_socket", "/var/run/proxydispatcher.s
ock")
...
     _________________________________________________________

1.5.2. sip_asymmetrics (string)

   It is the path to a file that lists regular expressions that
   match 'User-Agent' or 'Server' fields from clients that are
   asymmetric regarding SIP signaling. Needed to detect when a
   client is asymmetric regarding SIP signaling. An example file
   is in the config/ subdirectory.

   Default value is "/etc/openser/sip-asymmetric-clients". 

   Example 1-2. Setting sip_asymmetrics parameter
...
modparam("mediaproxy", "sip_asymmetrics", "/etc/openser/sip-asymmetrics
-clients")
...
     _________________________________________________________

1.5.3. rtp_asymmetrics (string)

   It is the path to a file that lists regular expressions that
   match 'User-Agent' or 'Server' fields from clients that are
   asymmetric regarding the RTP media. Needed to detect when a
   client is asymmetric regarding the RTP media. An example file
   is in the config/ subdirectory.

   Default value is "/etc/openser/rtp-asymmetric-clients". 

   Example 1-3. Setting rtp_asymmetrics parameter
...
modparam("mediaproxy", "rtp_asymmetrics", "/etc/openser/rtp-asymmetrics
-clients")
...
     _________________________________________________________

1.5.4. natping_interval (integer)

   It holds an integer value representing how often the module
   will send packets to all registered clients that are behind
   NAT to keep their opened channels alive. Represents an
   interval in seconds.

   Default value is 60. 

   Example 1-4. Setting natping_interval parameter
...
modparam("mediaproxy", "natping_interval", 20)
...
     _________________________________________________________

1.6. Exported Functions

1.6.1. client_nat_test(type)

   Tests if the client is behind NAT or not. The types of tests
   are specified by the type parameter which represents a sum of
   the following numbers (add the values of the ones you wish to
   perform tests for):

     * 1 - tests if client has a private IP address (as defined
       by RFC1918) in the Contact field of the SIP message.
     * 2 - tests if client has contacted OpenSER from an address
       that is different from the one in the Via field.
     * 4 - tests if client has a private IP address (as defined
       by RFC1918) in the top Via field of the SIP message.

   For example calling client_nat_test("3") in openser.cfg will
   perform first 2 tests listen above and return true as soon as
   one succeeds if both fail will return false.

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

   Example 1-5. client_nat_test usage
...
if (client_nat_test("3")) {
    .....
}
...
     _________________________________________________________

1.6.2. fix_contact()

   Will replace the IP:Port in the Contact field of the SIP
   message with the ones the SIP message was received from. For
   clients that are asymmetric regarding SIP signaling (as
   determined from the sip_asymmetrics file) will preserve the
   port.

   Usually called after an if (client_nat_test(type)) has
   succeded

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

   Example 1-6. fix_contact usage
...
if (client_nat_test("3")) {
    fix_contact();
}
...
     _________________________________________________________

1.6.3. use_media_proxy()

   Will make a call to the proxy server and replace the IPs and
   ports in the SDP body with the ones returned by the proxy
   server for each media stream that the SDP message describes.
   This will force the media streams to be routed through the
   proxy server.

   Called when you want to make the session go through a proxy
   server.

   This function has the following return codes:

     * +1 - successfully modified message (true value)
     * -1 - error in processing message (false value)
     * -2 - missing SDP body, nothing to process (false value)

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

   Example 1-7. use_media_proxy usage
...
if (method==INVITE) {
        use_media_proxy();
}
...
     _________________________________________________________

1.6.4. end_media_session()

   Will call on the proxy server to end the media session for
   that call this is done at the end of the call to instruct the
   proxy server to free the resources allocated to that call as
   well as to save log information about the call.

   Called when a session should end (BYE or CANCEL received).

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

   Example 1-8. end_media_session usage
...
if (method==BYE) {
        end_media_session();
}
...
     _________________________________________________________

1.7. Comparison with the nathelper module

   After reading all this you may wonder what this module can
   offer you that the nathelper module (a similar nat traversal
   solution) can't and why was necessary to develop this module.

   While at surface they seem to offer about the same
   functionality, there are a few core differences that make them
   quite different.

   The main and most notable difference is that mediaproxy offers
   a distributed environment, where the mediaproxy module can
   control multiple mediaproxy servers. The mediaproxy servers
   can be local or remote and they can be specified per domain or
   as defaults for domains that don't have their own mediaproxy
   servers defined. These mediaproxy servers can be arranged in
   load balancing and fallback schemes allowing the platform to
   scale up easily and also offer redundancy to keep the service
   running even if some of the mediaproxies go offline.
   Mediaproxy is able to detect the dead proxies and redistribute
   the calls among the other mediaproxies that are available.
   (More details about this can be found in the OpenSER
   MediaProxy documentation.)

   Another important difference is that mediaproxy tries to move
   the complex logic of decision from the OpenSER configuration
   file to the module and the proxy servers themselves. This is
   why there are very few functions in this module that take any
   parameters. Instead, control is achieved by modifying
   resources outside of openser.cfg. This includes for example
   specifying the mediaproxy servers using DNS SRV records, or
   declaring asymmetric clients in external files that are
   automatically re-read as soon as they change. This allows
   OpenSER to run without interruption or restarts. If one wants
   to change OpenSER's behavior, instead of changing openser.cfg
   and restarting OpenSER, one will change these external
   resources and OpenSER will adapt it's behavior on the fly
   without any need for restart.

   Another advantage of this is that openser.cfg becomes simpler
   and easier to maintain.
     _________________________________________________________

1.8. How to use sip_ping from the nathelper module

   The nathelper module provides an option to ping with real SIP
   messages instead of just sending 4 zero bytes, which has the
   advantage that the communication is bidirectional and thus
   some NATs that only keep the connection open if there is
   traffic from the inside won't close the pinholes (the 4 zero
   byte ping doesn't have a reply from inside the NAT).

   Example 1-9. Pinging exmaple configuration
...
loadmodule "/lib/openser/modules/mediaproxy.so"
loadmodule "/lib/openser/modules/nathelper.so"

modparam("mediaproxy", "natping_interval", 0)

modparam("nathelper", "rtpproxy_disable", 1)
modparam("nathelper", "natping_interval", 30)
modparam("nathelper", "sipping_from", "sip:ping@sipserver.net")

modparam("registrar", "nat_flag", 6)
modparam("registrar", "sip_natping_flag", 2)
....
....
if (method=="REGISTER") {
    setflag(6);  # nat
    setflag(2);  # sip_ping
    if (!save("location")) {
        sl_reply_error();
    }
}
...
     _________________________________________________________

Chapter 2. Developer's Guide

   The module does not provide any API to use in other OpenSER
   modules.
     _________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. Where can I find more about OpenSER?
   3.2. Where can I post a question about this module?
   3.3. How can I report a bug?

   3.1. Where can I find more about OpenSER?

   Take a look at http://openser.org/.

   3.2. Where can I post a question about this module?

   First at all check if your question was already answered on
   one of our mailing lists:

     * User Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/devel

   E-mails regarding any stable OpenSER release should be sent to
   <users@openser.org> and e-mails regarding development versions
   should be sent to <devel@openser.org>.

   If you want to keep the mail private, send it to
   <team@openser.org>.

   3.3. How can I report a bug?

   Please follow the guidelines provided at:
   http://sourceforge.net/tracker/?group_id=139143.