src/modules/topos/doc/topos_admin.xml
68717c2a
 <?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 -->
6deb5fcf
 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
68717c2a
 %docentities;
 
 ]>
 <!-- Module User's Guide -->
 
 <chapter>
956b5ae8
 
68717c2a
 	<title>&adminguide;</title>
956b5ae8
 
68717c2a
 	<section>
 	<title>Overview</title>
 	<para>
878971f2
 		This module offers topology hiding for INVITE-based dialogs, by stripping
 		the SIP routing headers that show topology details .
68717c2a
 		The script interpreter gets the SIP messages with full content,
 		so all existing functionality is preserved.
 	</para>
 	<para>
 		The module is transparent for the configuration writer. It only needs to be
878971f2
 		loaded (tune the module parameters if needed).
68717c2a
 	</para>
956b5ae8
 	<para>
4e659b5f
 		It also works for SIP MESSAGE or other requests that do not create
b8fc507c
 		a dialog (e.g., OPTIONS) -- record_route() must be used for them as well,
 		the headers are not going to be in the messages sent to the network, they
4e659b5f
 		are needed to know local addresses used to communicate with each side.
b8fc507c
         This module is designed to work for presence (SUBSCRIBE-based) dialogs too.
 	</para>
 	<para>
3333c392
 		The REGISTER and PUBLISH requests are skipped from processing
878971f2
 		by this module, expected to be terminated on a local SIP server.
956b5ae8
 	</para>
68717c2a
 	</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
4e659b5f
 				routing to ensure in-dialog requests are encoded/decoded (it
 				must be done for all initial requests).
68717c2a
 			</para>
 			</listitem>
 			<listitem>
 			<para>
 				<emphasis>database module</emphasis> - to store the data
 				for topology stripping and restoring.
 			</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>Parameters</title>
3868a27b
 	<section id="topos.p.storage">
 		<title><varname>storage</varname> (str)</title>
 		<para>
 		Type of storage, valid types are:
 		</para>
 		<itemizedlist>
 		<listitem>
 		<para>
 			<emphasis>db</emphasis> - Database Backend
 		</para>
 		</listitem>
 		<listitem>
 		<para>
 			<emphasis>redis</emphasis> - Redis Backend
 		</para>
 		</listitem>
 		</itemizedlist>
 		<para>
 		<emphasis>
 			Default value is <quote>db</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>storage</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("topos", "storage", "redis")
 ...
 </programlisting>
 		</example>
 	</section>
68717c2a
 	<section id="topos.p.db_url">
 		<title><varname>db_url</varname> (str)</title>
 		<para>
 		Database URL.
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>&defaultdb;</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>db_url</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("topos", "db_url", "&exampledb;")
 ...
 </programlisting>
 		</example>
 	</section>
 	<section id="topos.p.mask_callid">
 		<title><varname>mask_callid</varname> (int)</title>
3c358de7
 		<para>
 			Note: this functionality is not implemented yet - the
 			parameter is present in order to be in pair with topoh
 			module.
 		</para>
68717c2a
 		<para>
 			Whether to replace or not the Call-ID with another
 			unique id generated by &kamailio;.
 		</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("topos", "mask_callid", 1)
 ...
 </programlisting>
 		</example>
 	</section>
 	<section id="topos.p.sanity_checks">
 		<title><varname>sanity_checks</varname> (int)</title>
 		<para>
56c40ebe
 			If set to 1, topos module will bind to sanity module in order
68717c2a
 			to perform sanity checks over received SIP request. Default
 			sanity checks are done. It is useful to check if received request
b7e5e040
 			is well formatted before proceeding to encoding/decoding.
68717c2a
 		</para>
 		<para>
 		<emphasis>
 			Default value is 0 (do not bind to sanity module).
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>sanity_checks</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
56c40ebe
 modparam("topos", "sanity_checks", 1)
68717c2a
 ...
956b5ae8
 </programlisting>
 		</example>
 	</section>
4e9bea70
 	<section id="topos.p.branch_expire">
 		<title><varname>branch_expire</varname> (int)</title>
956b5ae8
 		<para>
 			Interval in seconds after which the branch records are deleted.
 		</para>
 		<para>
 		<emphasis>
 			Default value is 180 (3 min).
 		</emphasis>
 		</para>
 		<example>
4e9bea70
 		<title>Set <varname>branch_expire</varname> parameter</title>
956b5ae8
 		<programlisting format="linespecific">
 ...
4e9bea70
 modparam("topos", "branch_expire", 300)
956b5ae8
 ...
 </programlisting>
 		</example>
 	</section>
4e9bea70
 	<section id="topos.p.dialog_expire">
 		<title><varname>dialog_expire</varname> (int)</title>
956b5ae8
 		<para>
 			Interval in seconds after which the dialog records are deleted.
3ccf5ee6
 			Keep in mind that the module does not update the dialog timestamp
 			after the initial call setup on re-INVITEs or other in-dialog
 			messages. So set a large enough value (according your longest call
 			duration) to prevent problems in re-writing messages.
e90bfa7c
 			This key is only relevant for INVITE dialog.
3333c392
                         SUBSCRIBE dialog records lifetime are based on value set in expires
                         header. Moreover each re-SUBSCRIBEs update the dialog timestamp.
956b5ae8
 		</para>
 		<para>
 		<emphasis>
 			Default value is 10800 (3 hours).
 		</emphasis>
 		</para>
 		<example>
4e9bea70
 		<title>Set <varname>dialog_expire</varname> parameter</title>
956b5ae8
 		<programlisting format="linespecific">
 ...
4e9bea70
 modparam("topos", "dialog_expire", 3600)
956b5ae8
 ...
 </programlisting>
 		</example>
 	</section>
 	<section id="topos.p.clean_interval">
c42aca1e
 		<title><varname>clean_interval</varname> (int)</title>
956b5ae8
 		<para>
 			Interval in seconds to run the clean up of stored
 			records.
 		</para>
 		<para>
 		<emphasis>
 			Default value is 60 (1 min).
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>clean_interval</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("topos", "clean_interval", 30)
 ...
68717c2a
 </programlisting>
 		</example>
 	</section>
f6dc8715
 	<section id="topos.p.event_callback">
 		<title><varname>event_callback</varname> (str)</title>
 		<para>
 			The name of the function in the KEMI configuration file (embedded
 			scripting language such as Lua, Python, ...) to be executed instead
 			of event_route[...] blocks.
 		</para>
 		<para>
 			The function receives a string parameter with the name of the event.
 		</para>
 		<para>
 		<emphasis>
 			Default value is 'empty' (no function is executed for events).
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>event_callback</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("topos", "event_callback", "ksr_topos_event")
 ...
 -- event callback function implemented in Lua
 function ksr_topos_event(evname)
 	KSR.info("===== topos module triggered event: " .. evname .. "\n");
 	return 1;
 end
 ...
56f473bb
 </programlisting>
 		</example>
 	</section>
 	<section id="topos.p.event_mode">
 		<title><varname>event_mode</varname> (int)</title>
 		<para>
 			Control what event_route blocks to be executed. It is a bitmask of:
0b4edbe9
 			1 - execute event_route[topos:msg-outgoing]; 2 - execute
e90bfa7c
 			event_route[topos:msg-sending]; 4 execute
 			event_route[topos:msg-incoming]; 8 execute
 			event_route[topos:msg-receiving];.
56f473bb
 		</para>
 		<para>
 		<emphasis>
 			Default value is 3 (execute both event_route blocks).
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>event_mode</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("topos", "event_mode", 2)
 ...
8454dac6
 </programlisting>
 		</example>
 	</section>
 	<section id="topos.p.contact_host">
 		<title><varname>contact_host</varname> (str)</title>
 		<para>
 			You may need to control the host part of the Contact header added
0a9b039f
 			by topos. If the xavu_field_contact_host parameter is set, this value is
c9702415
 			ignored.
8454dac6
 
 			For example when using TLS with TOPOS the remote UAS must be able to open
 			a new TLS socket to the contact header.
 			In this case, the contact header must contain a domain name with a trusted CA
 			signed certitificate.
 		</para>
 		<para>
 		<emphasis>
 			Default value is taken from the Record-Route URI.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>contact_host</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("topos", "contact_host", "proxy.domain.com")
 ...
2ffc26aa
 </programlisting>
 		</example>
 	</section>
 	<section id="topos.p.contact_mode">
 		<title><varname>contact_mode</varname> (int)</title>
 		<para>
 		Control the mode where the key to lookup the message data from
 		the database or redis server is stored. The default is to use
 		the Contact user (0), alternatively a Contact URI parameter
 		can be used (1) with values from the SIP message, or from AVP
 		variables (2). This can be useful for interoperating which
 		gateways that need a certain user part in the Contact URI.
 		</para>
 		<para>In mode (1) the a-side contact user is taken from the
 		request URI and the b-side contact user from the Contact header
 		of the processed initial SIP request.
 		</para>
 		<para>If you use the mode (2), you need to configure the
7a3ad547
 		<emphasis>xavu_field_a_contact</emphasis> and <emphasis>xavu_field_b_contact</emphasis>
2ffc26aa
 		parameter. Furthermore you need to assign values to them during
 		the processing of the initial SIP request.
 		</para>
 		<para>
 		The name of the Contact URI parameter can be customized with
 		the <emphasis>cparam_name</emphasis> parameter.
 		</para>
 		<para>
 		<emphasis>
 			Default value is 0 - use the Contact user
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>contact_mode</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("topos", "contact_mode", 1)
 ...
 </programlisting>
 		</example>
 	</section>
 	<section id="topos.p.cparam_name">
 		<title><varname>cparam_name</varname> (int)</title>
 		<para>
 		Name of the Contact URI parameter to store the database or
 		redis server key for message lookup.
 		</para>
 		<para>
 		This parameter is only used when the <emphasis>contact_mode</emphasis>
 		parameter is set to <emphasis>1</emphasis> or <emphasis>2</emphasis>.
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>tps</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>cparam_name</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("topos", "cparam_name", "xyz")
 ...
 </programlisting>
 		</example>
 	</section>
7a3ad547
 	<section id="topos.p.xavu_cfg">
 		<title><varname>xavu_cfg</varname> (str)</title>
2ffc26aa
 		<para>
7a3ad547
 			Name of root XAVU to hold config-specific values to be used by
 			module at runtime.
 		</para>
 		<para>
 			Note: this parameter must be set if any other parameter prefixed
 			with `xavu_field_` is used.
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>NULL</quote> (disabled).
 		</emphasis>
 		</para>
 		<example>
a877e707
 		<title>Set <varname>xavu_cfg</varname> parameter</title>
7a3ad547
 		<programlisting format="linespecific">
 ...
 modparam("topos", "xavu_cfg", "_tps_")
0a9b039f
 modparam("topos", "xavu_field_a_contact", "a_contact")
7a3ad547
 ...
     $xavu(_tps_=>a_contact) = "...";
 ...
 </programlisting>
 		</example>
 	</section>
 	<section id="topos.p.xavu_field_a_contact">
0a9b039f
 		<title><varname>xavu_field_a_contact</varname> (str)</title>
7a3ad547
 		<para>
 			Name of the field inside root XAVU specifed by `xavu_cfg`
 			to evaluate for the A-side Contact Header user part. This parameter
 			is only necessary in contact_mode (2).
2ffc26aa
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>NULL</quote> (disabled).
 		</emphasis>
 		</para>
 		<example>
0a9b039f
 		<title>Set <varname>xavu_field_a_contact</varname> parameter</title>
2ffc26aa
 		<programlisting format="linespecific">
 ...
7a3ad547
 modparam("topos", "xavu_cfg", "_tps_")
0a9b039f
 modparam("topos", "xavu_field_a_contact", "a_contact")
7a3ad547
 ...
     $xavu(_tps_=>a_contact) = "...";
2ffc26aa
 ...
 </programlisting>
 		</example>
 	</section>
7a3ad547
 	<section id="topos.p.xavu_field_b_contact">
0a9b039f
 		<title><varname>xavu_field_b_contact</varname> (str)</title>
2ffc26aa
 		<para>
7a3ad547
 			Name of the field inside root XAVU specifed by `xavu_cfg`
 			to evaluate for the B-side Contact Header user part. This parameter
 			is only necessary in contact_mode (2).
2ffc26aa
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>NULL</quote> (disabled).
 		</emphasis>
 		</para>
 		<example>
0a9b039f
 		<title>Set <varname>xavu_field_b_contact</varname> parameter</title>
2ffc26aa
 		<programlisting format="linespecific">
 ...
7a3ad547
 modparam("topos", "xavu_cfg", "_tps_")
0a9b039f
 modparam("topos", "xavu_field_b_contact", "b_contact")
7a3ad547
 ...
     $xavu(_tps_=>b_contact) = "...";
 
cef21707
 ...
c9702415
 </programlisting>
 		</example>
 	</section>
40073c99
 	<section id="topos.p.xavu_field_contact_host">
7a3ad547
 		<title><varname>xavu_field_contact_host</varname> (str)</title>
c9702415
 		<para>
7a3ad547
 			Control from where to take the host part of the Contact header added
 			by topos. This parameter allows to take the value from an XAVU
 			during run-time, it specifies the field inside XAVU "xavu_cfg".
 			If this parameter is set, the contact_host parameter is ignored.
c9702415
 
 			For example when using TLS with TOPOS the remote UAS must be able to open
 			a new TLS socket to the contact header.
 			In this case, the contact header must contain a domain name with a trusted CA
 			signed certitificate.
 		</para>
 		<para>
 		<emphasis>
 			Default value is empty, not set.
 		</emphasis>
 		</para>
 		<example>
7a3ad547
 		<title>Set <varname>xavu_field_contact_host</varname> parameter</title>
c9702415
 		<programlisting format="linespecific">
 ...
7a3ad547
 modparam("topos", "xavu_cfg", "_tps_")
40073c99
 modparam("topos", "xavu_field_contact_host", "contact_host")
7a3ad547
 ...
     $xavu(_tps_=>contact_host) = "kamailio.org";
c9702415
 ...
a877e707
 </programlisting>
 		</example>
 	</section>
 	<section id="topos.p.rr_update">
 		<title><varname>rr_update</varname> (int)</title>
 		<para>
 			If set to 1, topos module will track and update record
 			route changes on re-invite.
 		</para>
 		<para>
 		<emphasis>
 			Default value is 0 (do not update record route changes within dialog).
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>rr_update</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("topos", "rr_update", 1)
 ...
f6dc8715
 </programlisting>
 		</example>
 	</section>
e90bfa7c
 	<section id="topos.p.context">
 		<title><varname>context</varname> (str)</title>
 		<para>
 			Set the global context for topos instance.
 		</para>
 		<para>
 			The value has to be maximum 12 characters.
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>NULL</quote> (disabled).
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>context</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("topos", "context", "srvone")
 ...
1ba5080e
 </programlisting>
 		</example>
 	</section>
 	<section id="topos.p.methods_nocontact">
 		<title><varname>methods_nocontact</varname> (str)</title>
 		<para>
 			List of SIP methods to skip adding Contact header for.
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>BYE,CANCEL,PRACK</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>methods_nocontact</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("topos", "methods_nocontact", "CANCEL,PRACK")
 ...
e90bfa7c
 </programlisting>
 		</example>
 	</section>
 	</section>
 
 	<section>
 	<title>Functions</title>
 	<section id="topos.f.tps_set_context">
 		<title>
 		<function moreinfo="none">tps_set_context(ctx)</function>
 		</title>
 		<para>
 			Update the context at runtime. If the value is emtpy string, then
 			the runtime context is reset.
 		</para>
 		<para>
 		This function can be used from ANY_ROUTE.
 		</para>
 		<example>
 		<title><function>tps_set_context</function> usage</title>
 		<programlisting format="linespecific">
 ...
 request_route {
     ...
     tps_set_context("srvone");
     ...
 }
 ...
 </programlisting>
 		</example>
f6dc8715
 	</section>
e90bfa7c
 	</section>
 
f6dc8715
 	<section>
 	<title>Event Routes</title>
de429e10
 	<section id="topos.e.msg_outgoing">
f6dc8715
 		<title>event_route[topos:msg-outgoing]</title>
 		<para>
 		It is executed before doing topology stripping processing for an outgoing
 		SIP message. If 'drop' is executed inside the event route, then the
 		module skips doing the topology hiding.
 		</para>
 		<para>
 		Inside the event route the variables $sndto(ip), $sndto(port) and
 		$sndto(proto) point to the destination. The SIP message is not the one
 		to be sent out, but an internally generated one at startup, to avoid
 		reparsing the outgoing SIP message for the cases when topology hiding
 		is not wanted.
 		</para>
 		<example>
 		<title>Usage of event_route[topos:msg-outgoing]</title>
 		<programlisting format="linespecific">
 ...
 event_route[topos:msg-outgoing] {
   if($sndto(ip)=="10.1.1.10") {
     drop;
   }
 }
 ...
56f473bb
 </programlisting>
 		</example>
 	</section>
de429e10
 	<section id="topos.e.msg_sending">
56f473bb
 		<title>event_route[topos:msg-sending]</title>
 		<para>
 		It is executed before doing topology stripping processing for a SIP
e42fcc93
 		message to be sent out, being executed after event_route[topos:msg-outgoing].
56f473bb
 		</para>
 		<para>
 		Inside the event route the variables $sndto(ip), $sndto(port) and
 		$sndto(proto) point to the destination. The SIP message is the one
 		to be sent out.
 		</para>
 		<example>
 		<title>Usage of event_route[topos:msg-sending]</title>
 		<programlisting format="linespecific">
 ...
 event_route[topos:msg-sending] {
   if(is_request() and $fU=="alice") {
     drop;
   }
 }
 ...
e90bfa7c
 </programlisting>
 		</example>
 	</section>
 	<section id="topos.e.msg_incoming">
 		<title>event_route[topos:msg-incoming]</title>
 		<para>
 		It is executed before doing topology stripping processing for an incoming
 		SIP message. If 'drop' is executed inside the event route, then the
 		module skips doing the topology hiding.
 		</para>
 		<para>
 		Inside the event route the variables $si, $sp and
 		$proto point to the source address. The SIP message is not the one
 		to be sent out, but an internally generated one at startup, to avoid
 		reparsing the outgoing SIP message for the cases when topology hiding
 		is not wanted.
 		</para>
 		<example>
 		<title>Usage of event_route[topos:msg-incoming]</title>
 		<programlisting format="linespecific">
 ...
 event_route[topos:msg-incoming] {
   if($si=="10.1.1.10") {
     drop;
   }
 }
 ...
 </programlisting>
 		</example>
 	</section>
 	<section id="topos.e.msg_receiving">
 		<title>event_route[topos:msg-receiving]</title>
 		<para>
 		It is executed before doing topology stripping processing for a SIP
 		message that was received, being executed after event_route[topos:msg-incoing].
 		</para>
 		<para>
 		Inside the event route the variables $si, $sp and
 		$proto point to the source address. The SIP message is the one
 		to be sent out.
 		</para>
 		<example>
 		<title>Usage of event_route[topos:msg-receoving]</title>
 		<programlisting format="linespecific">
 ...
 event_route[topos:msg-receiving] {
   if(is_request() and $fU=="alice") {
     drop;
   }
 }
 ...
f6dc8715
 </programlisting>
 		</example>
 	</section>
68717c2a
 	</section>
 </chapter>