modules/mediaproxy/doc/mediaproxy_admin.xml
33d03d8d
 <?xml version="1.0" encoding='ISO-8859-1'?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
 
 <!-- Include general documentation entities -->
 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
 %docentities;
 
 ]>
 
c26a66aa
 <!-- Module User's Guide -->
 
 <chapter>
59dfdd2e
   
   <title>&adminguide;</title>
   
   <section>
   <title>Overview</title>
     <para>
a118a328
       Mediaproxy is an &kamailio; module that is designed to allow automatic 
59dfdd2e
       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.
     </para>
   </section>
   
   <section>
   <title>Principle of operation</title>
     <para>
       This NAT traversal solution operates by placing a media relay 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 the relay while
       they think they talk directly with each other.
     </para>
 
     <para>
       Mediaproxy consists of 2 components:
       <itemizedlist>
         <listitem>
a118a328
           <para>The &kamailio; mediaproxy module</para>
59dfdd2e
         </listitem>
         <listitem>
           <para>
             An external application called MediaProxy which employs a
             dispatcher and multiple distributed media relays. This is
             available from http://ag-projects.com/MediaProxy.html
             (version 2.0.0 or newer is required by this module).
           </para>
         </listitem>
       </itemizedlist>
     </para>
 
     <para>
a118a328
       The mediaproxy dispatcher runs on the same machine as &kamailio;
59dfdd2e
       and its purpose is to select a media relay for a call. The media
       relay may run on the same machine as the dispatcher or on multiple
       remote hosts and its purpose is to forward the streams between the
       calling parties. To find out more about the architecture of MediaProxy
       please read the documentation that comes with it.
     </para>
 
     <para>
       To be able to act as a relay between the 2 user agents, the machine(s)
       running the module/proxy server must have a public IP address.
     </para>
 
     <para>
a118a328
       &kamailio; will ask the media relay to allocate as many ports as there are
59dfdd2e
       media streams in the SDP offer and answer. The media relay will send back
a118a328
       to &kamailio; the IP address and port(s) for them. Then &kamailio; will
59dfdd2e
       replace the original contact IP and RTP ports from the SDP messages with
       the ones provided by the media relay. By doing this, both user agents will
       try to contact the media relay instead of communicating directly with each
       other. Once the user agents contact the media relay, it will record the
       addresses they came from and will know where to forward packets received
       from the other endpoint. This is needed because the address/port the NAT
       box will allocate for the media streams is not known before they actually
       leave the NAT box. However the address of the media relay is always known
       (being a public IP) so the 2 endpoints know where to connect. After they
       do so, the relay learns their addresses and can forward packets between
       them.
     </para>
 
     <para>
       The SIP clients that will work transparently behind NAT when using
       mediaproxy, are the so-called symmetric clients. The symmetric clients
       have the particularity that use the same port to send and receive data.
       This must be true for both signaling and media for a client to work
       transparently with mediaproxy without any configuration on the NAT box.
     </para>
   </section>
 
   <section>
   <title>Features</title>
     <para>
       <itemizedlist>
         <listitem>
           <para>
             make symmetric clients work behind NAT transparently, with no
             configuration needed on the client's NAT box.
           </para>
         </listitem>
 
         <listitem>
           <para>
             have the ability to distribute RTP traffic on multiple media relays
             running on multiple hosts.
           </para>
         </listitem>
       </itemizedlist>
     </para>
   </section>
 
   <section>
   <title>Dependencies</title>
     <section>
a118a328
     <title>&kamailio; Modules</title>
59dfdd2e
       <para>
         The following modules must be loaded before this module:
         <itemizedlist>
           <listitem>
             <para>
               <emphasis>dialog</emphasis> module - if engage_media_proxy is used
               (see below the description of engage_media_proxy).
             </para>
           </listitem>
         </itemizedlist>
       </para>
     </section>
 
     <section>
     <title>External Libraries or Applications</title>
       <para>
         The following libraries or applications must be installed before
a118a328
         running &kamailio; with this module loaded:
59dfdd2e
         <itemizedlist>
           <listitem>
             <para>
               <emphasis>None</emphasis>.
             </para>
           </listitem>
         </itemizedlist>
       </para>
     </section>
   </section>
   
   <section>
   <title>Exported parameters</title>
     <section>
     <title><varname>disable</varname> (int)</title>
       <para>
         Boolean flag that specifies if mediaproxy should be disabled. This
         is useful when you want to use the same openser configuration in
         two different context, one using mediaproxy, the other not. In the
         case mediaproxy is disabled, calls to its functions will have no
         effect, allowing you to use the same configuration without changes.
       </para>
 
       <para>
         <emphasis>
           Default value is <quote>0</quote>.
         </emphasis>
       </para>
 
       <example>
       <title>Setting the <varname>disable</varname> parameter</title>
         <programlisting format="linespecific">
c26a66aa
 ...
59dfdd2e
 modparam("mediaproxy", "disable", 1)
c26a66aa
 ...
59dfdd2e
         </programlisting>
       </example>
     </section>
 
     <section>
     <title><varname>mediaproxy_socket</varname> (string)</title>
       <para>
         It is the path to the filesystem socket where the mediaproxy dispatcher
         listens for commands from the module.
       </para>
 
       <para>
         <emphasis>
           Default value is 
             <quote>/var/run/mediaproxy/dispatcher.sock</quote>.
         </emphasis>
       </para>
 
       <example>
       <title>Setting the <varname>mediaproxy_socket</varname> parameter</title>
         <programlisting format="linespecific">
c26a66aa
 ...
59dfdd2e
 modparam("mediaproxy", "mediaproxy_socket", "/var/run/mediaproxy/dispatcher.sock")
c26a66aa
 ...
59dfdd2e
         </programlisting>
       </example>
     </section>
 
     <section>
     <title><varname>mediaproxy_timeout</varname> (int)</title>
       <para>
         How much time (in milliseconds) to wait for an answer from the
         mediaproxy dispatcher.
       </para>
 
       <para>
         <emphasis>
           Default value is <quote>500</quote>.
         </emphasis>
       </para>
 
       <example>
       <title>Setting the <varname>mediaproxy_timeout</varname> parameter</title>
         <programlisting format="linespecific">
c26a66aa
 ...
59dfdd2e
 modparam("mediaproxy", "mediaproxy_timeout", 500)
c26a66aa
 ...
59dfdd2e
         </programlisting>
       </example>
     </section>
 
     <section>
     <title><varname>signaling_ip_avp</varname> (string)</title>
       <para>
         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.
       </para>
 
       <para>
         <emphasis>
           Default value is <quote>$avp(s:signaling_ip)</quote>.
         </emphasis>
       </para>
 
       <example>
       <title>Setting the <varname>signaling_ip_avp</varname> parameter</title>
         <programlisting format="linespecific">
54d32b43
 ...
253554bb
 modparam("mediaproxy", "signaling_ip_avp", "$avp(s:nat_ip)")
54d32b43
 ...
59dfdd2e
         </programlisting>
       </example>
     </section>
 
     <section>
     <title><varname>media_relay_avp</varname> (string)</title>
       <para>
         Specification of the AVP which holds an optional application
         defined media relay IP address of a particular media relay that
         is preferred to be used for the current call. If an IP address
         is written to this AVP before calling use_media_proxy(), it
         will be preferred by the dispatcher over the normal selection
         algorithm.
       </para>
 
       <para>
         <emphasis>
           Default value is <quote>$avp(s:media_relay)</quote>.
         </emphasis>
       </para>
 
       <example>
       <title>Setting the <varname>media_relay_avp</varname> parameter</title>
         <programlisting format="linespecific">
c26a66aa
 ...
59dfdd2e
 modparam("mediaproxy", "media_relay_avp", "$avp(s:media_relay)")
c26a66aa
 ...
59dfdd2e
         </programlisting>
       </example>
     </section>
   </section>
 
   <section>
   <title>Exported Functions</title>
     <section>
     <title><function moreinfo="none">engage_media_proxy()</function></title>
       <para>
         Trigger the use of MediaProxy for all the dialog requests and
         replies that have an SDP body. This needs to be called only
         once for the first INVITE in a dialog. After that it will use
         the dialog module to trace the dialog and automatically call
         use_media_proxy() on every request and reply that belongs to
         the dialog and has an SDP body. When the dialog ends it will
         also call automatically end_media_session(). All of these are
         called internally on dialog callbacks, so for this function to
         work, the dialog module must be loaded and configured.
       </para>
 
       <para>
         This function is an advanced mechanism to use a media relay
         without having to manually call a function on each message that
         belongs to the dialog. However this method is less flexible,
         because once things were set in motion by calling this function
         on the first INVITE, it cannot be stopped, not even by calling
         end_media_session(). It will only stop when the dialog ends.
         Until then it will modify the SDP content of every in-dialog
         message to make it use a media relay. If one needs more control
         over the process, like starting to use mediaproxy only later in
         the failure route, or stopping to use mediaproxy in the failure
         route, then the use_media_proxy and end_media_session functions
         should be used, and manually called as appropriate. Using this
         function should NOT be mixed with either of use_media_proxy()
         or end_media_session().
       </para>
 
       <para>
         This function can be used from REQUEST_ROUTE.
       </para>
 
       <example>
       <title>Using the <function>engage_media_proxy</function> function</title>
         <programlisting format="linespecific">
c26a66aa
 ...
59dfdd2e
 if (method==INVITE &amp;&amp; !has_totag()) {
     # We can also use a specific media relay if we need to
     #$avp(s:media_relay) = "1.2.3.4";
     engage_media_proxy();
c26a66aa
 }
 ...
59dfdd2e
         </programlisting>
       </example>
     </section>
 
     <section>
     <title><function moreinfo="none">use_media_proxy()</function></title>
       <para>
         Will make a call to the dispatcher and replace the IPs and ports
         in the SDP body with the ones returned by the media relay for
         each supported media stream in the SDP body. This will force the
         media streams to be routed through the media relay. If a mix of
         supported and unsupported streams are present in the SDP, only
         the supported streams will be modified, while the unsupported
         streams will be left alone.
       </para>
 
       <para>
         This function should NOT be mixed with engage_media_proxy().
       </para>
 
       <para>This function has the following return codes:</para>
       <para>
         <itemizedlist>
         <listitem><para>
           +1 - successfully modified message (true value)
         </para></listitem>
         <listitem><para>
           -1 - error in processing message (false value)
         </para></listitem>
         <listitem><para>
           -2 - missing SDP body, nothing to process (false value)
         </para></listitem>
         </itemizedlist>
       </para>
 
       <para>
         This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
       </para>
 
       <example>
       <title>Using the <function>use_media_proxy</function> function</title>
         <programlisting format="linespecific">
ee199390
 ...
 if (method==INVITE) {
59dfdd2e
     # We can also use a specific media relay if we need to
     #$avp(s:media_relay) = "1.2.3.4";
3df23431
     use_media_proxy();
ee199390
 }
 ...
59dfdd2e
         </programlisting>
       </example>
     </section>
 
     <section>
     <title><function moreinfo="none">end_media_session()</function></title>
       <para>
         Will call on the dispatcher to inform the media relay to end the
         media session. This is done when a call ends, to instruct the media
         relay to release the resources allocated to that call as well as
         to save logging information about the media session. Called on BYE,
         CANCEL or failures.
       </para>
 
       <para>
         This function should NOT be mixed with engage_media_proxy().
       </para>
 
       <para>
         This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
       </para>    
 
       <example>
       <title>Using the <function>end_media_session</function> function</title>
         <programlisting format="linespecific">
c26a66aa
 ...
 if (method==BYE) {
3df23431
     end_media_session();
c26a66aa
 }
 ...
59dfdd2e
         </programlisting>
       </example>
     </section>
   </section>
c26a66aa
 
 </chapter>