topos: added support for 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
227         </section>
228 </chapter>
229