kamailio/modules/rtpproxy/doc/rtpproxy_admin.xml

<?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;

]>

<!-- Module User's Guide -->

<chapter>
	
	<title>&adminguide;</title>
	
	<section>
	<title>Overview</title>
	<para>
		This is a module that enables media streams to be proxied
		via an rtpproxy.
	</para>
	<para>
		Known devices that get along over &nat;s with rtpproxy are ATAs
		(as clients) and Cisco Gateways (since 12.2(T)) as servers.  See <ulink
		url="http://www.cisco.com/en/US/products/sw/iosswrel/ps1839/products_feature_guide09186a0080110bf9.html">
		http://www.cisco.com/en/US/products/sw/iosswrel/ps1839/products_feature_guide09186a0080110bf9.html"></ulink>
	</para>
	</section>

	<section>
	<title>Multiple RTPProxy usage</title>
	<para>
		Currently, the rtpproxy module can support multiple rtpproxies for
		balancing/distribution and control/selection purposes.
	</para>
	<para>
		The module allows the definition of several sets of rtpproxies -
		load-balancing will be performed over a set and the user has the
		ability to choose what set should be used. The set is selected via
		its id - the id being defined along with the set. Refer to the
		<quote>rtpproxy_sock</quote> module parameter definition for syntax
		description.
	</para>
	<para>
		The balancing inside a set is done automatically by the module based on
		the weight of each rtpproxy from the set.
	</para>
	<para>
		The selection of the set is done from script prior using
		unforce_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer()
		functions - see the set_rtp_proxy_set() function.
	</para>
	<para>
		For backward compatibility reasons, a set with no id take by default
		the id 0. Also if no set is explicitly set before
		unforce_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer()
		the 0 id set will be used.
	</para>
	<para>
		IMPORTANT: if you use multiple sets, take care and use the same set for
		both rtpproxy_offer()/rtpproxy_answer() and unforce_rtpproxy()!!
	</para>
	</section>

	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before
		running &kamailio; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
	<title>Exported Parameters</title>
	<section>
		<title><varname>rtpproxy_sock</varname> (string)</title>
		<para>
		Definition of socket(s) used to connect to (a set) RTPProxy. It may
		specify a UNIX socket or an IPv4/IPv6 UDP socket.
		</para>
		<para>
		<emphasis>
			Default value is <quote>NONE</quote> (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>rtpproxy_sock</varname> parameter</title>
		<programlisting format="linespecific">
...
# single rtproxy
modparam("rtpproxy", "rtpproxy_sock", "udp:localhost:12221")
# multiple rtproxies for LB
modparam("rtpproxy", "rtpproxy_sock",
	"udp:localhost:12221 udp:localhost:12222")
# multiple sets of multiple rtproxies
modparam("rtpproxy", "rtpproxy_sock",
	"1 == udp:localhost:12221 udp:localhost:12222")
modparam("rtpproxy", "rtpproxy_sock",
	"2 == udp:localhost:12225")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>rtpproxy_disable_tout</varname> (integer)</title>
		<para>
		Once RTPProxy was found unreachable and marked as disable, rtpproxy
		will not attempt to establish communication to RTPProxy for
		rtpproxy_disable_tout seconds.
		</para>
		<para>
		<emphasis>
			Default value is <quote>60</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>rtpproxy_disable_tout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rtpproxy", "rtpproxy_disable_tout", 20)
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>rtpproxy_tout</varname> (integer)</title>
		<para>
		Timeout value in waiting for reply from RTPProxy.
		</para>
		<para>
		<emphasis>
			Default value is <quote>1</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>rtpproxy_tout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rtpproxy", "rtpproxy_tout", 2)
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>rtpproxy_retr</varname> (integer)</title>
		<para>
		How many times rtpproxy should retry to send and receive after
		timeout was generated.
		</para>
		<para>
		<emphasis>
			Default value is <quote>5</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>rtpproxy_retr</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rtpproxy", "rtpproxy_retr", 2)
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>force_socket</varname> (string)</title>
		<para>
		Socket to be forced in communicating to RTPProxy. It makes sense only
		for UDP communication. If no one specified, the OS will choose.
		</para>
		<para>
		<emphasis>
			Default value is <quote>NULL</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>force_socket</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rtpproxy", "force_socket", "localhost:33333")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>nortpproxy_str</varname> (string)</title>
		<para>
		The parameter sets the SDP attribute used by rtpproxy to mark
		the packet SDP informations have already been mangled.
		</para>
		<para>
		If empty string, no marker will be added or checked.
		</para>
		<note><para>
		The string must be a complete SDP line, including the EOH (\r\n).
		</para></note>
		<para>
		<emphasis>
			Default value is <quote>a=nortpproxy:yes\r\n</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>nortpproxy_str</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rtpproxy", "nortpproxy_str", "a=sdpmangled:yes\r\n")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>timeout_socket</varname> (string)</title>
		<para>
		The parameter sets timeout socket, which is transmitted to the RTP-Proxy.
		</para>
		<para>
		If it is an empty string, no timeout socket will be transmitted to the RTP-Proxy.
		</para>
		<para>
		<emphasis>
			Default value is <quote></quote> (nothing).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>timeout_socket</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("nathelper", "timeout_socket", "xmlrpc:http://127.0.0.1:8000/RPC2")
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Exported Functions</title>
	<section>
		<title>
		<function moreinfo="none">set_rtp_proxy_set()</function>
		</title>
		<para>
		Sets the Id of the rtpproxy set to be used for the next
		unforce_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer()
		command.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		BRANCH_ROUTE.
		</para>
		<example>
		<title><function>fix_nated_contact</function> usage</title>
		<programlisting format="linespecific">
...
set_rtp_proxy_set("2");
rtpproxy_offer();
...
</programlisting>
		</example>
	</section>
        <section>
                <title>
                <function moreinfo="none">rtpproxy_offer([flags [, ip_address]])</function>
                </title>
                <para>
                Rewrites &sdp; body to ensure that media is passed through
                an &rtp; proxy. To be invoked
		on INVITE for the cases the SDPs are in INVITE and 200 OK and on 200 OK
		when SDPs are in 200 OK and ACK.
                </para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>flags</emphasis> - flags to turn on some features.
			</para>
			<itemizedlist>
				<listitem><para>
				<emphasis>a</emphasis> - flags that UA from which message is
				received doesn't support symmetric RTP. (automatically sets the 'r' flag)
				</para></listitem>
				<listitem><para>
				<emphasis>l</emphasis> - force <quote>lookup</quote>, that is,
				only rewrite SDP when corresponding session is already exists
				in the RTP proxy. By default is on when the session is to be
				completed.
				</para></listitem>
				<listitem><para>
				<emphasis>i, e</emphasis> - these flags specify the direction of the SIP
				message. These flags only make sense when rtpproxy is running in bridge mode.
				'i' means internal network (LAN), 'e' means external network (WAN). 'i'
				corresponds to rtpproxy's first interface, 'e' corresponds to rtpproxy's
				second interface. You always have to specify two flags to define
				the incoming network and the outgoing network. For example, 'ie' should be
				used for SIP message received from the local interface and sent out on the
				external interface, and 'ei' vice versa. Other options are 'ii' and 'ee'.
				So, for example if a SIP requests is processed with 'ie' flags, the corresponding
				response must be processed with 'ie' flags.
				</para><para>
				Note: As rtpproxy is in bridge mode per default asymmetric, you have to specify
				the 'w' flag for clients behind NAT! See also above notes!
				</para></listitem>
				<listitem><para>
				<emphasis>f</emphasis> - instructs rtpproxy to ignore marks
				inserted by another rtpproxy in transit to indicate that the
				session is already goes through another proxy. Allows creating
				chain of proxies.
				</para></listitem>
				<listitem><para>
				<emphasis>r</emphasis> - flags that IP address in SDP should
				be trusted. Without this flag, rtpproxy ignores address in
				the SDP and uses source address of the SIP message as media
				address which is passed to the RTP proxy.
				</para></listitem>
				<listitem><para>
				<emphasis>o</emphasis> - flags that IP from the origin
				description (o=) should be also changed.
				</para></listitem>
				<listitem><para>
				<emphasis>c</emphasis> - flags to change the session-level
				SDP connection (c=) IP if media-description also includes
				connection information.
				</para></listitem>
				<listitem><para>
				<emphasis>w</emphasis> - flags that for the UA from which
				message is received, support symmetric RTP must be forced.
				</para></listitem>
				<listitem><para>
				<emphasis>zNN</emphasis> - requests the RTPproxy to perform
				re-packetization of RTP traffic coming from the UA which
				has sent the current message to increase or decrease payload
				size per each RTP packet forwarded if possible.  The NN is the
				target payload size in ms, for the most codecs its value should
				be in 10ms increments, however for some codecs the increment
				could differ (e.g. 30ms for GSM or 20ms for G.723).  The
				RTPproxy would select the closest value supported by the codec.
				This feature could be used for significantly reducing bandwith
				overhead for low bitrate codecs, for example with G.729 going
				from 10ms to 100ms saves two thirds of the network bandwith.
				</para></listitem>
			</itemizedlist>
		</listitem>
		<listitem><para>
		<emphasis>ip_address</emphasis> - new SDP IP address.
		</para></listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE.
                </para>
		<example>
		<title><function>rtpproxy_offer</function> usage</title>
		<programlisting format="linespecific">
route {
...
    if (is_method("INVITE")) {
        if (has_sdp()) {
            if (rtpproxy_offer())
                t_on_reply("1");
        } else {
            t_on_reply("2");
        }
    }
    if (is_method("ACK") &amp;&amp; has_sdp())
        rtpproxy_answer();
...
}

onreply_route[1]
{
...
    if (has_sdp())
        rtpproxy_answer();
...
}

onreply_route[2]
{
...
    if (has_sdp())
        rtpproxy_offer();
...
}
</programlisting>
                </example>
	</section>
        <section>
                <title>
                <function moreinfo="none">rtpproxy_answer([flags [, ip_address]])</function>
                </title>
		<para>
		Rewrites &sdp; body to ensure that media is passed through
		an &rtp; proxy. To be invoked
		on 200 OK for the cases the SDPs are in INVITE and 200 OK and on ACK
		when SDPs are in 200 OK and ACK.
		</para>
		<para>
		See rtpproxy_answer() function description above for the meaning of the
		parameters.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		 <title><function>rtpproxy_answer</function> usage</title>
		<para>
		See rtpproxy_offer() function example above for example.
		</para>
		</example>
        </section>
	<section>
		<title>
		<function moreinfo="none">unforce_rtp_proxy()</function>
		</title>
		<para>
		Tears down the RTPProxy session for the current call.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>unforce_rtp_proxy</function> usage</title>
		<programlisting format="linespecific">
...
unforce_rtp_proxy();
...
</programlisting>
		</example>
	</section>
	<section id="rtpproxy_stream2xxx">
	<title>
	    <function>rtpproxy_stream2uac(prompt_name, count)</function>,
	    <function>rtpproxy_stream2uas(prompt_name, count)</function>
	</title>
	<para>
	    Instruct the RTPproxy to stream prompt/announcement pre-encoded with
	    the makeann command from the RTPproxy distribution. The uac/uas
	    suffix selects who will hear the announcement relatively to the current
	    transaction - UAC or UAS. For example invoking the
	    <function>rtpproxy_stream2uac</function> in the request processing
	    block on ACK transaction will play the prompt to the UA that has
	    generated original INVITE and ACK while
	    <function>rtpproxy_stop_stream2uas</function> on 183 in reply
	    processing block will play the prompt to the UA that has generated 183.
	</para>
	<para>
	    Apart from generating announcements, another possible application
	    of this function is implementing music on hold (MOH) functionality.
	    When count is -1, the streaming will be in loop indefinitely until
	    the appropriate <function>rtpproxy_stop_stream2xxx</function> is issued.
	</para>
	<para>
	    In order to work correctly, functions require that the session in the
	    RTPproxy already exists. Also those functions don't alted SDP, so that
	    they are not substitute for calling <function>rtpproxy_offer</function>
	    or <function>rtpproxy_answer</function>.
	</para>
	<para>
	    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>prompt_name</emphasis> - name of the prompt to
		    stream.  Should be either absolute pathname or pathname
		    relative to the directory where RTPproxy runs.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    <emphasis>count</emphasis> - number of times the prompt
		    should be repeated.  The value of -1 means that it will
		    be streaming in loop indefinitely, until appropriate
		    <function>rtpproxy_stop_stream2xxx</function> is issued.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>rtpproxy_stream2xxx</function> usage</title>
	    <programlisting>
...
    if (is_method("INVITE")) {
        rtpproxy_offer();
        if (detect_hold()) {
            rtpproxy_stream2uas("/var/rtpproxy/prompts/music_on_hold", "-1");
        } else {
            rtpproxy_stop_stream2uas();
        };
    };
...
	    </programlisting>
	</example>
	</section>
	<section id="rtpproxy_stop_stream2xxx">
	<title>
	    <function>rtpproxy_stop_stream2uac()</function>,
	    <function>rtpproxy_stop_stream2uas()</function>
	</title>
	<para>
	    Stop streaming of announcement/prompt/MOH started previously by the
	    respective <function>rtpproxy_stream2xxx</function>.  The uac/uas
	    suffix selects whose announcement relatively to tha current
	    transaction should be stopped - UAC or UAS.
	</para>
	<para>
	    These functions can be used from REQUEST_ROUTE, ONREPLY_ROUTE.
	</para>
	</section>
	<section>
		<title>
		<function moreinfo="none">start_recording()</function>
		</title>
		<para>
		This command will send a signal to the RTP-Proxy to record
		the RTP stream on the RTP-Proxy.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
		</para>
		<example>
		<title><function>start_recording</function> usage</title>
		<programlisting format="linespecific">
...
start_recording();
...
		</programlisting>
		</example>
	</section>


	</section>

	<section>
		<title>Exported Pseudo Variables</title>
		<section>
			<title><function moreinfo="none">$rtpstart</function></title>
			<para>
			Returns the RTP-Statistics from the RTP-Proxy. The RTP-Statistics from the RTP-Proxy
			are provided as a string and it does contain several packet-counters. The statistics
			must be retrieved before the session is deleted	(before unforce_rtpproxy).
			</para>

		<example>
		<title>$rtpstat-Usage</title>
		<programlisting format="linespecific">
...
    append_hf("X-RTP-Statistics: $rtpstat\r\n");
...
		</programlisting>
		</example>
	        </section>

	</section>

	<section>
		<title><acronym>MI</acronym> Commands</title>
		<section>
			<title><function moreinfo="none">nh_enable_rtpp</function></title>
			<para>
			Enables a rtp proxy if parameter value is greater than 0.
			Disables it if a zero value is given.
			</para>
			<para>
			The first parameter is the rtp proxy url (exactly as defined in
			the config file).
			</para>
			<para>
			The second parameter value must be a number in decimal.
			</para>
			<para>
			NOTE: if a rtpproxy is defined multiple times (in the same or
			diferente sete), all its instances will be enables/disabled.
			</para>
			<example>
			<title>
			<function moreinfo="none">nh_enable_rtpp</function> usage</title>
			<programlisting format="linespecific">
...
$ &ctltool; fifo nh_enable_rtpp udp:192.168.2.133:8081 0
...
			</programlisting>
			</example>
		</section>
				
			<section>
			<title><function moreinfo="none">nh_show_rtpp</function></title>
			<para>
			Displays all the rtp proxies and their information: set and
			status (disabled or not, weight and recheck_ticks).
			</para>
			<para>
			No parameter.
			</para>
			<example>
			<title>
				<function moreinfo="none">nh_show_rtpp</function> usage</title>
			<programlisting format="linespecific">
...
$ &ctltool; fifo nh_show_rtpp
...
			</programlisting>
			</example>
		</section>
	</section>

</chapter>