<?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 module hides the routing headers that show topology details.
		It it is not affected by the server being transaction stateless or
		stateful. The script interpretor gets the SIP messages decoded,
		so all functionality existing so far is preserved.
	</para>
	<para>
		The module is transparent for the configuration writer. It only needs to be
		loaded (tune the parameters if needed). The SIP server can be restarted
		whitout affecting ongoing calls - once it is up, can encode/decode
		topology details, thus no call will be lost.
	</para>
	<para>
		By using same mask_key, many SIP servers can decode the message,
		for example, applicable for servers behind load balancers.
	</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>rr module</emphasis> - server must perform record
				routing to ensure in-dialog requests are encoded/decoded.
			</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>. In the future the module can be
				enhnaced to use a stronger encryption algorithm.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Exported Parameters</title>
	<section>
		<title><varname>mask_key</varname> (str)</title>
		<para>
		Keyword to mask the headers.
		</para>
		<para>
		<emphasis>
			Default value is "_static_value_".
		</emphasis>
		</para>
		<example>
		<title>Set <varname>mask_key</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("topoh", "mask_key", "some secret here")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>mask_callid</varname> (integer)</title>
		<para>
			Whether to encode the Call-id: header. Some SIP extensions include
			the Call-id in the SIP message payload or header, so it is safe to
			not encode Call-id in such cases. Well-known extensions such as
			call transfer or conference join will be added to work with encoded
			Call-id.
		</para>
		<para>
		<emphasis>
			Default value is 0 (do not mask).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>mask_callid</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("topoh", "mask_callid", 1)
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>uparam_name</varname> (str)</title>
		<para>
		Name of URI param where to store encoded value.
		</para>
		<para>
		<emphasis>
			Default value is "line".
		</emphasis>
		</para>
		<example>
		<title>Set <varname>uparam_name</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("topoh", "uparam_name", "myparam")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>uparam_prefix</varname> (str)</title>
		<para>
		Prefix to be added in encoded URI params.
		</para>
		<para>
		<emphasis>
			Default value is "sr-".
		</emphasis>
		</para>
		<example>
		<title>Set <varname>uparam_prefix</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("topoh", "uparam_prefix", "xyz")
...
</programlisting>
		</example>
	</section>
		<section>
		<title><varname>vparam_name</varname> (str)</title>
		<para>
		Name of Via: parameter where to store encoded value.
		</para>
		<para>
		<emphasis>
			Default value is "branch".
		</emphasis>
		</para>
		<example>
		<title>Set <varname>vparam_name</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("topoh", "vparam_name", "myv")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>vparam_prefix</varname> (str)</title>
		<para>
		Prefix to be added in encoded Via: parameters.
		</para>
		<para>
		<emphasis>
			Default value is "z9hG4bKsr-".
		</emphasis>
		</para>
		<example>
		<title>Set <varname>vparam_prefix</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("topoh", "vparam_prefix", "xyz")
...
</programlisting>
		</example>
	</section>

	</section>
	<section>
	<title>Exported Functions</title>
	<section>
		<para>
			None.
		</para>
	</section>
	</section>
</chapter>