topos: docs for event_callback param and event_route[topos:msg-outgoing]
[sip-router] / src / modules / topos / doc / topos_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13
14         <title>&adminguide;</title>
15
16         <section>
17         <title>Overview</title>
18         <para>
19                 This module offers topology hiding by stripping the SIP routing
20                 headers that show topology details.
21                 The script interpreter gets the SIP messages with full content,
22                 so all existing functionality is preserved.
23         </para>
24         <para>
25                 The module is transparent for the configuration writer. It only needs to be
26                 loaded (tune the parameters if needed).
27         </para>
28         <para>
29                 It works for SIP MESSAGE requests.
30         </para>
31         </section>
32         <section>
33         <title>Dependencies</title>
34         <section>
35                 <title>&kamailio; Modules</title>
36                 <para>
37                 The following modules must be loaded before this module:
38                         <itemizedlist>
39                         <listitem>
40                         <para>
41                                 <emphasis>rr module</emphasis> - server must perform record
42                                 routing to ensure in-dialog requests are encoded/decoded.
43                         </para>
44                         </listitem>
45                         <listitem>
46                         <para>
47                                 <emphasis>database module</emphasis> - to store the data
48                                 for topology stripping and restoring.
49                         </para>
50                         </listitem>
51                         </itemizedlist>
52                 </para>
53         </section>
54         <section>
55                 <title>External Libraries or Applications</title>
56                 <para>
57                 The following libraries or applications must be installed before running
58                 &kamailio; with this module loaded:
59                         <itemizedlist>
60                         <listitem>
61                         <para>
62                                 <emphasis>none</emphasis>.
63                         </para>
64                         </listitem>
65                         </itemizedlist>
66                 </para>
67         </section>
68         </section>
69         <section>
70         <title>Parameters</title>
71         <section id="topos.p.storage">
72                 <title><varname>storage</varname> (str)</title>
73                 <para>
74                 Type of storage, valid types are:
75                 </para>
76                 <itemizedlist>
77                 <listitem>
78                 <para>
79                         <emphasis>db</emphasis> - Database Backend
80                 </para>
81                 </listitem>
82                 <listitem>
83                 <para>
84                         <emphasis>redis</emphasis> - Redis Backend
85                 </para>
86                 </listitem>
87                 </itemizedlist>
88                 <para>
89                 <emphasis>
90                         Default value is <quote>db</quote>.
91                 </emphasis>
92                 </para>
93                 <example>
94                 <title>Set <varname>storage</varname> parameter</title>
95                 <programlisting format="linespecific">
96 ...
97 modparam("topos", "storage", "redis")
98 ...
99 </programlisting>
100                 </example>
101         </section>
102         <section id="topos.p.db_url">
103                 <title><varname>db_url</varname> (str)</title>
104                 <para>
105                 Database URL.
106                 </para>
107                 <para>
108                 <emphasis>
109                         Default value is <quote>&defaultdb;</quote>.
110                 </emphasis>
111                 </para>
112                 <example>
113                 <title>Set <varname>db_url</varname> parameter</title>
114                 <programlisting format="linespecific">
115 ...
116 modparam("topos", "db_url", "&exampledb;")
117 ...
118 </programlisting>
119                 </example>
120         </section>
121         <section id="topos.p.mask_callid">
122                 <title><varname>mask_callid</varname> (int)</title>
123                 <para>
124                         Note: this functionality is not implemented yet - the
125                         parameter is present in order to be in pair with topoh
126                         module.
127                 </para>
128                 <para>
129                         Whether to replace or not the Call-ID with another
130                         unique id generated by &kamailio;.
131                 </para>
132                 <para>
133                 <emphasis>
134                         Default value is 0 (do not mask).
135                 </emphasis>
136                 </para>
137                 <example>
138                 <title>Set <varname>mask_callid</varname> parameter</title>
139                 <programlisting format="linespecific">
140 ...
141 modparam("topos", "mask_callid", 1)
142 ...
143 </programlisting>
144                 </example>
145         </section>
146         <section id="topos.p.sanity_checks">
147                 <title><varname>sanity_checks</varname> (int)</title>
148                 <para>
149                         If set to 1, topoh module will bind to sanity module in order
150                         to perform sanity checks over received SIP request. Default
151                         sanity checks are done. It is useful to check if received request
152                         is well formated before proceeding to encoding/decoding.
153                 </para>
154                 <para>
155                 <emphasis>
156                         Default value is 0 (do not bind to sanity module).
157                 </emphasis>
158                 </para>
159                 <example>
160                 <title>Set <varname>sanity_checks</varname> parameter</title>
161                 <programlisting format="linespecific">
162 ...
163 modparam("topoh", "sanity_checks", 1)
164 ...
165 </programlisting>
166                 </example>
167         </section>
168         <section id="topos.p.branch_expire">
169                 <title><varname>branch_expire</varname> (int)</title>
170                 <para>
171                         Interval in seconds after which the branch records are deleted.
172                 </para>
173                 <para>
174                 <emphasis>
175                         Default value is 180 (3 min).
176                 </emphasis>
177                 </para>
178                 <example>
179                 <title>Set <varname>branch_expire</varname> parameter</title>
180                 <programlisting format="linespecific">
181 ...
182 modparam("topos", "branch_expire", 300)
183 ...
184 </programlisting>
185                 </example>
186         </section>
187         <section id="topos.p.dialog_expire">
188                 <title><varname>dialog_expire</varname> (int)</title>
189                 <para>
190                         Interval in seconds after which the dialog records are deleted.
191                 </para>
192                 <para>
193                 <emphasis>
194                         Default value is 10800 (3 hours).
195                 </emphasis>
196                 </para>
197                 <example>
198                 <title>Set <varname>dialog_expire</varname> parameter</title>
199                 <programlisting format="linespecific">
200 ...
201 modparam("topos", "dialog_expire", 3600)
202 ...
203 </programlisting>
204                 </example>
205         </section>
206         <section id="topos.p.clean_interval">
207                 <title><varname>clean_interval</varname> (int)</title>
208                 <para>
209                         Interval in seconds to run the clean up of stored
210                         records.
211                 </para>
212                 <para>
213                 <emphasis>
214                         Default value is 60 (1 min).
215                 </emphasis>
216                 </para>
217                 <example>
218                 <title>Set <varname>clean_interval</varname> parameter</title>
219                 <programlisting format="linespecific">
220 ...
221 modparam("topos", "clean_interval", 30)
222 ...
223 </programlisting>
224                 </example>
225         </section>
226         <section id="topos.p.event_callback">
227                 <title><varname>event_callback</varname> (str)</title>
228                 <para>
229                         The name of the function in the KEMI configuration file (embedded
230                         scripting language such as Lua, Python, ...) to be executed instead
231                         of event_route[...] blocks.
232                 </para>
233                 <para>
234                         The function receives a string parameter with the name of the event.
235                 </para>
236                 <para>
237                 <emphasis>
238                         Default value is 'empty' (no function is executed for events).
239                 </emphasis>
240                 </para>
241                 <example>
242                 <title>Set <varname>event_callback</varname> parameter</title>
243                 <programlisting format="linespecific">
244 ...
245 modparam("topos", "event_callback", "ksr_topos_event")
246 ...
247 -- event callback function implemented in Lua
248 function ksr_topos_event(evname)
249         KSR.info("===== topos module triggered event: " .. evname .. "\n");
250         return 1;
251 end
252 ...
253 </programlisting>
254                 </example>
255         </section>
256         </section>
257         <section>
258         <title>Event Routes</title>
259         <section>
260                 <title>event_route[topos:msg-outgoing]</title>
261                 <para>
262                 It is executed before doing topology stripping processing for an outgoing
263                 SIP message. If 'drop' is executed inside the event route, then the
264                 module skips doing the topology hiding.
265                 </para>
266                 <para>
267                 Inside the event route the variables $sndto(ip), $sndto(port) and
268                 $sndto(proto) point to the destination. The SIP message is not the one
269                 to be sent out, but an internally generated one at startup, to avoid
270                 reparsing the outgoing SIP message for the cases when topology hiding
271                 is not wanted.
272                 </para>
273                 <example>
274                 <title>Usage of event_route[topos:msg-outgoing]</title>
275                 <programlisting format="linespecific">
276 ...
277 event_route[topos:msg-outgoing] {
278   if($sndto(ip)=="10.1.1.10") {
279     drop;
280   }
281 }
282 ...
283 </programlisting>
284                 </example>
285         </section>
286         </section>
287 </chapter>
288