iptrtpproxy Documentation cleanup

And a missing file from sanity module

modules/iptrtpproxy/README

@@ -7,15 +7,99 @@ Tomas Mandys
    Copyright © 2007 Tomas Mandys
      __________________________________________________________________
 
+   Table of Contents
+
+   1.
+
+        1. Overview
+        2. Dependencies
+        3. Parameters
+
+              3.1. config (string)
+              3.2. switchboard (string)
+              3.3. rpc_heartbeat_timeout (int)
+              3.4. hostname (string)
+              3.5. declare_codec (string)
+              3.6. codec_set (string)
+
+        4. Functions
+
+              4.1. iptrtpproxy_alloc(gate_a_to_b [, existing_sess_ids])
+              4.2. iptrtpproxy_update(gate_a_to_b, session_ids)
+              4.3. iptrtpproxy_adjust_timeout(gate_a_to_b, session_ids)
+              4.4. iptrtpproxy_delete(session_ids)
+              4.5. iptrtpproxy_authorize_media()
+              4.6. iptrtpproxy_set_param(param, value)
+              4.7.
+                      iptrtpproxy_set_param("(aggregation/switchboard)_by_sip_
+                      ip_(a/b)", sip_ip)
+
+              4.8. iptrtpproxy_set_param("protected_session_ids",
+                      sess_ids)
+
+              4.9. iptrtpproxy_set_param("o_name", value)
+              4.10. iptrtpproxy_set_param("o_addr", value)
+              4.11. iptrtpproxy_set_param("codec_set", value)
+              4.12. iptrtpproxy_set_param("remove_codec_mask", value)
+
+        5. Selects
+
+              5.1. @iptrtpproxy.session_ids
+              5.2. @iptrtpproxy.sdp_ip
+              5.3. @iptrtpproxy.o_name
+              5.4. @iptrtpproxy.o_addr
+              5.5. @iptrtpproxy.auth_rights
+              5.6. @iptrtpproxy.active_media_num
+
    List of Examples
 
-   1. Declare switchboard
-   2. Declare codec_set
-   3. iptrtpproxy_alloc usage
-   4. iptrtpproxy_update usage
-   5. iptrtpproxy_adjust_timeout usage
-   6. iptrtpproxy_delete usage
-   7. iptrtpproxy_authorize_media usage
+   1.1. Declare switchboard
+   1.2. Declare codec_set
+   1.3. iptrtpproxy_alloc usage
+   1.4. iptrtpproxy_update usage
+   1.5. iptrtpproxy_adjust_timeout usage
+   1.6. iptrtpproxy_delete usage
+   1.7. iptrtpproxy_authorize_media usage
+
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+   3. Parameters
+
+        3.1. config (string)
+        3.2. switchboard (string)
+        3.3. rpc_heartbeat_timeout (int)
+        3.4. hostname (string)
+        3.5. declare_codec (string)
+        3.6. codec_set (string)
+
+   4. Functions
+
+        4.1. iptrtpproxy_alloc(gate_a_to_b [, existing_sess_ids])
+        4.2. iptrtpproxy_update(gate_a_to_b, session_ids)
+        4.3. iptrtpproxy_adjust_timeout(gate_a_to_b, session_ids)
+        4.4. iptrtpproxy_delete(session_ids)
+        4.5. iptrtpproxy_authorize_media()
+        4.6. iptrtpproxy_set_param(param, value)
+        4.7.
+                iptrtpproxy_set_param("(aggregation/switchboard)_by_sip_ip_(a/
+                b)", sip_ip)
+
+        4.8. iptrtpproxy_set_param("protected_session_ids", sess_ids)
+        4.9. iptrtpproxy_set_param("o_name", value)
+        4.10. iptrtpproxy_set_param("o_addr", value)
+        4.11. iptrtpproxy_set_param("codec_set", value)
+        4.12. iptrtpproxy_set_param("remove_codec_mask", value)
+
+   5. Selects
+
+        5.1. @iptrtpproxy.session_ids
+        5.2. @iptrtpproxy.sdp_ip
+        5.3. @iptrtpproxy.o_name
+        5.4. @iptrtpproxy.o_addr
+        5.5. @iptrtpproxy.auth_rights
+        5.6. @iptrtpproxy.active_media_num
 
 1. Overview
 
@@ -98,7 +182,7 @@ Note
    to widden bandwidth. Aggregation will take sip-addr from the first
    switchboard of its.
 
-   Example 1. Declare switchboard
+   Example 1.1. Declare switchboard
         ...
         modparam("iptrtpproxy", "config", "/etc/iptrtpproxy.cfg");
         modparam("iptrtpproxy", "switchboard", "name=my1;sip-addr-a=1.2.3.4;sip-
@@ -161,7 +245,7 @@ addr-b=3.4.5.6;aggregation=my23");
    unlimited). It will override bandwidth limited by
    iptrtpproxy_set_param("throttle_*").
 
-   Example 2. Declare codec_set
+   Example 1.2. Declare codec_set
         ...
         # enable all codecs, default state when codec is declared
         modparam("iptrtpproxy", "codec_set", "name=cs1;media_type=*;max_streams=
@@ -228,7 +312,7 @@ s=10000;rtcp_bytes=1000");
      * function returns true is a session was created, identifier is
        available via select @iptrtpproxy.session_ids.
 
-   Example 3. iptrtpproxy_alloc usage
+   Example 1.3. iptrtpproxy_alloc usage
         ...
         if (!iptrtpproxy_set_param("aggregation_by_sip_ip_a", "@received.ip")) {
                 if (!iptrtpproxy_set_param("switchboard_by_sip_ip_a", "@received
@@ -285,7 +369,7 @@ eval.get[-1]")) {
        in onreply route, retransmission replies are not eaten be tm
        module!
 
-   Example 4. iptrtpproxy_update usage
+   Example 1.4. iptrtpproxy_update usage
         ...
         # load $sess_ids from dialog
         if (iptrtpproxy_update("0", $sess_ids)) {
@@ -301,7 +385,7 @@ eval.get[-1]")) {
      * if gate_a_to_b bit 0 is set then it regards to gate-a to gate-b
        direction.
 
-   Example 5. iptrtpproxy_adjust_timeout usage
+   Example 1.5. iptrtpproxy_adjust_timeout usage
         ...
         # load $sess_ids from dialog
         if (status=~"18[0-9]") {
@@ -321,7 +405,7 @@ eval.get[-1]")) {
    protected_session_ids list is provided then this set is excluded from
    sessions to be deleted.
 
-   Example 6. iptrtpproxy_delete usage
+   Example 1.6. iptrtpproxy_delete usage
         ...
         # load $sess_ids from dialog
         iptrtpproxy_delete($sess_ids);
@@ -339,7 +423,7 @@ eval.get[-1]")) {
    function may be called several times to authorize using more codec
    sets.
 
-   Example 7. iptrtpproxy_authorize_media usage
+   Example 1.7. iptrtpproxy_authorize_media usage
         ...
         if (@iptrtpproxy.active_media_num == "0") break;
         iptrtpproxy_set_param("codec_set", "cs2");

modules/iptrtpproxy/doc/iptrtpproxy.xml

@@ -30,162 +30,6 @@
     </bookinfo>
 
 
-    <section id="iptrtpproxy.overview">
-	<title>Overview</title>
-	<para>
-	This module provides similar functionality as <emphasis>nathelper</emphasis> but
-	communicates with <emphasis>netfilter</emphasis> kernel 
-	<emphasis>xt_RTPPROXY</emphasis> module using
-	the <emphasis>libipt_RTPPROXY</emphasis> userspace library. 
-	All RTP streams are manipulated directly in kernel space, no data is copied from 
-	kernel to userspace and back, it reduces load and delay. 
-	See <ulink url="http://www.2p.cz/en/netfilter_rtp_proxy">
-	http://www.2p.cz/en/netfilter_rtp_proxy</ulink> for more details.
-	</para>
-
-	<para>
-	This &kamailio; module is written as a light-weight module, there is no 
-	dialog managment as in <emphasis>Nathelper</emphasis>. The reason is that such an API
-	should be provided by core or a specialized dialog manager module.
-	Because such module is not in git, session information may be stored 
-	in extra attributes of the <emphasis>avp_db</emphasis> module and
-	the session id itself in record route as cookie, see the <emphasis>rr</emphasis> module.
-	</para>
-
-	<para>
-	It should be able to support all cases as re-invites when SIP client offers media change in SDP and
-	when number of medias in offer/answer are different. 
-	</para>
-
-	<para>
-	<emphasis>Nathelper</emphasis> may be still used for testing if client is behind the NAT.
-	</para>
-
-	<para>
-	There is also support for media authorization. Number of codec sets may be defined.
-	When a message containing SDP offer/answer is being processed then current codecs
-	and streams may be inspected, removed or signallized according a codec set.
-	</para>
-
-
-	<para>
-	Limitations:
-	<itemizedlist>
-		<listitem>
-			<para>
-		 Only IPv4 addresses are supported.
-			</para>
-		</listitem>
-		<listitem>
-			<para>
-		 More media streams per session supported
-			</para>
-		</listitem>
-	</itemizedlist>
-	</para>
-    </section>
-
-	<section id="iptrtpproxy.dep">
-	<title>Dependencies</title>
-				   
-	<para>
-	The following libraries or applications must be installed before
-	running &kamailio; with this module loaded:
-	<itemizedlist>
-		<listitem>
-		<para>
-		netfilter xt_RTPPROXY &amp; libipt_RTPPROXY,
-	    see <ulink url="http://www.2p.cz/en/netfilter_rtp_proxy">http://www.2p.cz/en/netfilter_rtp_proxy</ulink>
-		</para>
-		</listitem>
-	</itemizedlist>
-	</para>
-	<note><para>
-	The modules Makefile must be edited and iptdir setup to the directory with
-	the iptable sources (if different from ~/iptables). Alternatively
-	compile the module using: 
-	<programlisting>
-		make -C modules/iptrtpproxy iptdir=path_to_iptables_src
-	</programlisting>
-	</para></note>
-	</section>
-
-
-	<xi:include href="iptrtpproxy_params.xml"/>
-    	<xi:include href="iptrtpproxy_functions.xml"/>
-
-
-	<section>
-		<title>Selects</title>
-
-		<section id="iptrtpproxy.session_ids">
-		<title>
-			<function>@iptrtpproxy.session_ids</function>
-		</title>
-		<para>
-		Returns sessions allocated/updated in <function>iptrtpproxy_alloc/update</function>.
-		</para>
-
-		<para>
-		The format is:
-		</para>
-
-		<programlisting>
-
-switchboard_name [ ":" [ session_id "/" created ] * ( "," session_id "/" created ) ] ]
-session_id = * ( [0-9] )   ; empty when no session allocated
-created = timestamp
-</programlisting>
-
-		</section>
-
-		<section id="iptrtpproxy.sdp_ip">
-		<title>
-			<function>@iptrtpproxy.sdp_ip</function>
-		</title>
-		<para>
-		Return first rewritten IP provided at SDP <emphasis>c=</emphasis> line.
-		</para>
-		</section>
-
-		<section id="iptrtpproxy.o_name">
-		<title>
-			<function>@iptrtpproxy.o_name</function>
-		</title>
-		<para>
-		Return username from original <emphasis>o=</emphasis> line.
-		</para>
-		</section>
-
-		<section id="iptrtpproxy.o_addr">
-		<title>
-			<function>@iptrtpproxy.o_addr</function>
-		</title>
-		<para>
-		Return address from original <emphasis>o=</emphasis> line.
-		</para>
-		</section>
-
-		<section id="iptrtpproxy.auth_rights">
-		<title>
-			<function>@iptrtpproxy.auth_rights</function>
-		</title>
-		<para>
-		Result of <function>iptrtpproxy_authorize_media</function>.
-		</para>
-		</section>
-
-		<section id="iptrtpproxy.active_media_num">
-		<title>
-			<function>@iptrtpproxy.active_media_num</function>
-		</title>
-		<para>
-		Returns number of active media streams in SDP. <function>iptrtpproxy_authorize_media</function>
-		may disable some streams, i.e. returned value may change after authorization.
-		</para>
-		</section>
-
-	</section>
-
+	<xi:include href="iptrtpproxy_admin.xml"/>
 </book>
 

modules/iptrtpproxy/doc/iptrtpproxy_functions.xml → modules/iptrtpproxy/doc/iptrtpproxy_admin.xml

@@ -10,6 +10,219 @@
 >
 
 
+<chapter>
+    <section id="iptrtpproxy.overview">
+	<title>Overview</title>
+	<para>
+	This module provides similar functionality as <emphasis>nathelper</emphasis> but
+	communicates with <emphasis>netfilter</emphasis> kernel 
+	<emphasis>xt_RTPPROXY</emphasis> module using
+	the <emphasis>libipt_RTPPROXY</emphasis> userspace library. 
+	All RTP streams are manipulated directly in kernel space, no data is copied from 
+	kernel to userspace and back, it reduces load and delay. 
+	See <ulink url="http://www.2p.cz/en/netfilter_rtp_proxy">
+	http://www.2p.cz/en/netfilter_rtp_proxy</ulink> for more details.
+	</para>
+
+	<para>
+	This &kamailio; module is written as a light-weight module, there is no 
+	dialog managment as in <emphasis>Nathelper</emphasis>. The reason is that such an API
+	should be provided by core or a specialized dialog manager module.
+	Because such module is not in git, session information may be stored 
+	in extra attributes of the <emphasis>avp_db</emphasis> module and
+	the session id itself in record route as cookie, see the <emphasis>rr</emphasis> module.
+	</para>
+
+	<para>
+	It should be able to support all cases as re-invites when SIP client offers media change in SDP and
+	when number of medias in offer/answer are different. 
+	</para>
+
+	<para>
+	<emphasis>Nathelper</emphasis> may be still used for testing if client is behind the NAT.
+	</para>
+
+	<para>
+	There is also support for media authorization. Number of codec sets may be defined.
+	When a message containing SDP offer/answer is being processed then current codecs
+	and streams may be inspected, removed or signallized according a codec set.
+	</para>
+
+
+	<para>
+	Limitations:
+	<itemizedlist>
+		<listitem>
+			<para>
+		 Only IPv4 addresses are supported.
+			</para>
+		</listitem>
+		<listitem>
+			<para>
+		 More media streams per session supported
+			</para>
+		</listitem>
+	</itemizedlist>
+	</para>
+    </section>
+
+	<section id="iptrtpproxy.dep">
+	<title>Dependencies</title>
+				   
+	<para>
+	The following libraries or applications must be installed before
+	running &kamailio; with this module loaded:
+	<itemizedlist>
+		<listitem>
+		<para>
+		netfilter xt_RTPPROXY &amp; libipt_RTPPROXY,
+	    see <ulink url="http://www.2p.cz/en/netfilter_rtp_proxy">http://www.2p.cz/en/netfilter_rtp_proxy</ulink>
+		</para>
+		</listitem>
+	</itemizedlist>
+	</para>
+	<note><para>
+	The modules Makefile must be edited and iptdir setup to the directory with
+	the iptable sources (if different from ~/iptables). Alternatively
+	compile the module using: 
+	<programlisting>
+		make -C modules/iptrtpproxy iptdir=path_to_iptables_src
+	</programlisting>
+	</para></note>
+	</section>
+
+	<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>
 	<section id="iptrtpproxy.funcs" xmlns:xi="http://www.w3.org/2001/XInclude">
 		<title>Functions</title>
 
@@ -340,4 +553,76 @@
 		</para>
 		</section>
 	</section>
+	<section>
+		<title>Selects</title>
+
+		<section id="iptrtpproxy.session_ids">
+		<title>
+			<function>@iptrtpproxy.session_ids</function>
+		</title>
+		<para>
+		Returns sessions allocated/updated in <function>iptrtpproxy_alloc/update</function>.
+		</para>
+
+		<para>
+		The format is:
+		</para>
+
+		<programlisting>
+
+switchboard_name [ ":" [ session_id "/" created ] * ( "," session_id "/" created ) ] ]
+session_id = * ( [0-9] )   ; empty when no session allocated
+created = timestamp
+</programlisting>
+
+		</section>
+
+		<section id="iptrtpproxy.sdp_ip">
+		<title>
+			<function>@iptrtpproxy.sdp_ip</function>
+		</title>
+		<para>
+		Return first rewritten IP provided at SDP <emphasis>c=</emphasis> line.
+		</para>
+		</section>
+
+		<section id="iptrtpproxy.o_name">
+		<title>
+			<function>@iptrtpproxy.o_name</function>
+		</title>
+		<para>
+		Return username from original <emphasis>o=</emphasis> line.
+		</para>
+		</section>
+
+		<section id="iptrtpproxy.o_addr">
+		<title>
+			<function>@iptrtpproxy.o_addr</function>
+		</title>
+		<para>
+		Return address from original <emphasis>o=</emphasis> line.
+		</para>
+		</section>
+
+		<section id="iptrtpproxy.auth_rights">
+		<title>
+			<function>@iptrtpproxy.auth_rights</function>
+		</title>
+		<para>
+		Result of <function>iptrtpproxy_authorize_media</function>.
+		</para>
+		</section>
+
+		<section id="iptrtpproxy.active_media_num">
+		<title>
+			<function>@iptrtpproxy.active_media_num</function>
+		</title>
+		<para>
+		Returns number of active media streams in SDP. <function>iptrtpproxy_authorize_media</function>
+		may disable some streams, i.e. returned value may change after authorization.
+		</para>
+		</section>
+
+	</section>
 
+</chapter>

modules/iptrtpproxy/doc/iptrtpproxy_params.xml

@@ -1,145 +0,0 @@
-<?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>
-

modules/sanity/doc/sanity_admin.xml

@@ -8,6 +8,7 @@
 
 ]>
 
+<chapter>
 <section id="sanity.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
     <sectioninfo>
     </sectioninfo>
@@ -97,5 +98,75 @@ modparam("sanity", "autodrop", 1)
 	    </programlisting>
 	</example>
 	</section>
+</section>
 
+   <section id="sanity.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+    </sectioninfo>
+    <title>Functions</title>
+    <section id="sanity_check">
+	    <title>
+		<function>sanity_check([msg_checks [, uri_checks]])</function>
+	    </title>
+	<para>
+		This function makes a row of sanity checks over the given SIP request. The
+		behavior of the function is also controlled by 'autodrop' parameter.
+		If autodrop=0, the function returns false (-1) if one of the checks failed.
+		When autodrop=1, the function stops the execution of configuration file.
+		In both cases, if one of the checks fails the module sends a precise error
+		reply via SL send_reply(). Thus there is no need to reply with a generic 
+		error message.
+	</para>
+	<example>
+	    <title><function>sanity_check</function> usage</title>
+	    <programlisting>
+<![CDATA[
+...
+if (!sanity_check()) {
+	exit;
+}
+...
+]]>
+	    </programlisting>
+	</example>
+	<para>
+		Optionally the function takes an integer argument which overwrites
+		the global module parameter default_checks. This allows to make
+		certain test from script regions. The integer value is again the sum
+		of the checks (like for the module parameter) which should be executed
+		at this function call.
+	</para>
+	<example>
+	    <title><function>sanity_check</function> usage with parameter</title>
+	    <programlisting>
+<![CDATA[
+...
+if (method=="REGISTER" && !sanity_check("256")) {
+	/* the register contains an invalid expires value and is replied with a 400 */
+	exit;
+}
+...
+]]>
+	    </programlisting>
+	</example>
+	<para>
+		Optionally the function takes a second integer argument which
+		overwrites the global module parameter uri_checks and thus determines
+		which URIs will be checked if the parse uri test will be executed.
+	</para>
+	<example>
+		<title><function>sanity_check</function> usage with two parameters</title>
+		<programlisting>
+<![CDATA[
+...
+if (method=="INVITE" && !sanity_check("1024", "6")) {
+	/* the INVITE contains an invalid From or To header and is replied with a 400 */
+	exit;
+}
+...
+]]>
+		</programlisting>
+	</example>
+    </section>
 </section>
+</chapter>