kamailio/modules/iptrtpproxy/doc/params.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
	[ <!ENTITY % local.common.attrib
	 "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
	 <!-- Include general documentation entities -->
	 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
	 %docentities;
	]
>


	<section id="iptrtpproxy.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">

		<title>Parameters</title>

		<section id="config">
		<title><varname>config</varname> (string)</title>
		<para>
  References <emphasis>iptrtpproxy.cfg</emphasis>, see <emphasis>iptrtpproxy_helper</emphasis>. Default value
		is <emphasis>/etc/iptrtpproxy.cfg</emphasis>. If only codec authorization is to be used then 
		<emphasis>/dev/null</emphasis> may be used.
		</para>
		</section>

		<section id="switchboard">
		<title><varname>switchboard</varname> (string)</title>
		<para>
  References <emphasis>xt_RTPPROXY</emphasis> switchboard for usage by ser module. 
		</para>
		<para>
		The format is:
		</para>
			<programlisting>
  "name=" value * ( ";" name "=" value )

  name =  "aggregation" | "sip-addr-" 
			</programlisting>

		<para>
  The <emphasis>name</emphasis> is the switchboard name as declared in config and will be used by script functions and references switchboard. 
  It's mandatory parameter. The special name <emphasis>*</emphasis> set values for all switchboards. 
		</para>
		<para>
  The <emphasis>sip-addr</emphasis> is address used by <function>iptrtpproxy_ser_param(by_sip_ip)</function> to find a switchboard for particular
  connection. If not explicitly configured then RTP switchboard gate address are used for this feature. 
		</para>
		<para>
The <emphasis>aggregation</emphasis> enables to aggregate more switchboards in cluster and to widden bandwidth.
Aggregation will take <emphasis>sip-addr</emphasis> from the first switchboard of its. 
		</para>
		<example>
			<title>Declare <varname>switchboard</varname></title>
			<programlisting>
	...
	modparam("iptrtpproxy", "config", "/etc/iptrtpproxy.cfg");
	modparam("iptrtpproxy", "switchboard", "name=my1;sip-addr-a=1.2.3.4;sip-addr-b=5.6.7.8");
	modparam("iptrtpproxy", "switchboard", "name=my2;sip-addr-a=2.3.4.5;sip-addr-b=3.4.5.6;aggregation=my23");
	modparam("iptrtpproxy", "switchboard", "name=my3;aggregation=my23");
	modparam("iptrtpproxy", "switchboard", "name=*;aggregation=my123");
	...
			</programlisting>
		</example>
		</section>

		<section id="rpc_heartbeat_timeout">
		<title><varname>rpc_heartbeat_timeout</varname> (int)</title>
		<para>
		Timeout in seconds used for rerequest remote RTP proxy via RPC command after preceeding error.
		In other words if a RPC server is unresponsive at the moment then next attempt will be forced
		after this timeout. Default value is <emphasis>30</emphasis>.
		</para>
		</section>

		<section id="hostname">
		<title><varname>hostname</varname> (string)</title>
		<para>
		The hostname used by RPC to identify machine where Ser is running to communicate which RTP proxy
		via local interface. Default value is taken from system hostname.
		</para>
		</section>

		<section id="declare_codec">
		<title><varname>declare_codec</varname> (string)</title>
		<para>
		There are basic implicit codecs compiled in module, more codecs may be added by this parameter (one codec per modparam).
		</para>
		</section>

		<section id="codec_set">
		<title><varname>codec_set</varname> (string)</title>
		<para>
		Declares new codec set. Codecs are declared for each media type independently. 
		</para>
		<para>
		The format is:
		</para>
			<programlisting>
  "name=" value * ( ";" name "=" value )

  name =  "media_type" | "rights" | "codecs" | "max_streams" | ( "rtp" | "rtcp" ) "_" ( "bytes" | "packets" )

  media_types = "audio" | "video" | "application" | "text" | "message" | "data" | "control" | "?" | "*"
			</programlisting>		

		<para>
  The <emphasis>name</emphasis> is the codec set name to be defined.
		</para>
		<para>
  The <emphasis>media_type</emphasis> belongs to type at <emphasis>m=</emphasis> SDP line. Question mark means
  "unknown media" type and asterisk "all media types".
		</para>
		<para>
  The <emphasis>max_streams</emphasis> defines how many streams (m= lines) is allowed per media type.
		</para>
		<para>
  The <emphasis>rights</emphasis> defines if particular codec is allowed <emphasis>0</emphasis>, disallowed, i.e. will be removed
  if bit AND operation with <function>remove_codec_mask</function> is non-zero or its presence will be signallized by <function>@iptrtpproxy.auth_rights</function> (any other value).
		</para>
		<para>
  The <emphasis>codecs</emphasis> comma separated list of codecs. Previous <emphasis>media_type&amp;rights</emphasis> will be applied.
		</para>
		<para>
  The <emphasis>rtp/rtcp_bytes/packets</emphasis> limits bandwidth per <emphasis>media_type</emphasis> (0 is unlimited). It will override
  bandwidth limited by <function>iptrtpproxy_set_param("throttle_*")</function>.
		</para>
		<example>
			<title>Declare <varname>codec_set</varname></title>
			<programlisting>
	...
	# enable all codecs, default state when codec is declared
	modparam("iptrtpproxy", "codec_set", "name=cs1;media_type=*;max_streams=9999;rights=0;codecs=*");
	# allow only 2 audio and 1 video stream
	modparam("iptrtpproxy", "codec_set", "name=cs2;media_type=*;max_streams=0;media_type=audio;max_streams=2;media_type=video;max_streams=1");
	# dtto, allow only a few audio and video codecs, GSM codec is allowed but signallized
	modparam("iptrtpproxy", "codec_set", "name=cs3;media_type=*;max_streams=0;rights=1;codecs=*;media_type=audio;max_streams=2;rights=0;codecs=PCMU,G729,G728,parityfec,telephone-events;rights=2;codecs=GSM;media_type=video;max_streams=1;rights=0;codecs=jpeg,parityfec");
	# limit max. bandwidth for video¨	
	modparam("iptrtpproxy", "codec_set", "name=cs4;media_type=video;rtp_bytes=10000;rtcp_bytes=1000");
	...
			</programlisting>
		</example>
		</section>

	</section>