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. Dependencies

              1.5.1. OpenSER Modules
              1.5.2. External Libraries or Applications

        1.6. Exported parameters

              1.6.1. mediaproxy_socket (string)
              1.6.2. sip_asymmetrics (string)
              1.6.3. rtp_asymmetrics (string)
              1.6.4. natping_interval (integer)
              1.6.5. signaling_ip_avp (string)
              1.6.6. domain_avp (string)

        1.7. Exported Functions

              1.7.1. client_nat_test(type)
              1.7.2. fix_contact()
              1.7.3. use_media_proxy()
              1.7.4. end_media_session()

        1.8. Comparison with the nathelper module
        1.9. 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. Setting signaling_ip_avp parameter
   1-6. Setting domain_avp parameter
   1-7. client_nat_test usage
   1-8. fix_contact usage
   1-9. use_media_proxy usage
   1-10. Using mediaproxies from a specific domain
   1-11. end_media_session usage
   1-12. Pinging example configuration
     __________________________________________________________

Chapter 1. User's Guide

1.1. Overview

   Mediaproxy is an 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. Dependencies

1.5.1. OpenSER Modules

   The following modules must be loaded before this module:

     * usrloc module - this is required if pinging of contacts
       behind NAT is enabled. In this case the nat_bflag must also
       be defined on the ursloc module.
     __________________________________________________________

1.5.2. External Libraries or Applications

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

     * None.
     __________________________________________________________

1.6. Exported parameters

1.6.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.so
ck")
...
     __________________________________________________________

1.6.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.6.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.6.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.5. signaling_ip_avp (string)

   Specification of the AVP which holds the IP address from where
   the SIP signaling originated. If this AVP is set it will be
   used to get the signaling IP address, else the source IP
   address from where the SIP message was received will be used.
   This AVP is meant to be used in cases where there are more than
   one proxy in the call setup path and the proxy that actually
   starts mediaproxy doesn't receive the SIP messages directly
   from the UA and it cannot determine the NAT IP address from
   where the signaling originated. In such a case attaching a SIP
   header at the first proxy and then copying that header's value
   into the signaling_ip_avp on the proxy that starts mediaproxy
   will allow it to get the correct NAT IP address from where the
   SIP signaling originated.

   Default value is "$avp(s:signaling_ip)".

   Example 1-5. Setting signaling_ip_avp parameter
...
modparam("mediaproxy", "signaling_ip_avp", "$avp(s:nat_ip)")
...
     __________________________________________________________

1.6.6. domain_avp (string)

   Specification of the AVP which holds an optional application
   defined domain name, that specifies the domain to be used to
   select the mediaproxies for the current call. If a domain name
   is written to this AVP before calling use_media_proxy(), it
   will be used to select the mediaproxies for the call,
   overwriting the normal selection process based on the
   caller/callee domain.

   Default value is "$avp(s:mediaproxy_domain)".

   Example 1-6. Setting domain_avp parameter
...
modparam("mediaproxy", "domain_avp", "$avp(s:mediaproxy_domain)")
...
     __________________________________________________________

1.7. Exported Functions

1.7.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-7. client_nat_test usage
...
if (client_nat_test("3")) {
    .....
}
...
     __________________________________________________________

1.7.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-8. fix_contact usage
...
if (client_nat_test("3")) {
    fix_contact();
}
...
     __________________________________________________________

1.7.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-9. use_media_proxy usage
...
if (method==INVITE) {
    use_media_proxy();
}
...

   Example 1-10. Using mediaproxies from a specific domain
...
if (method==INVITE) {
    $avp(s:mediaproxy_domain) = "example.com";
    use_media_proxy();
}
...
     __________________________________________________________

1.7.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-11. end_media_session usage
...
if (method==BYE) {
    end_media_session();
}
...
     __________________________________________________________

1.8. 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.9. 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-12. Pinging example 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.
