1TSILO Module
2
3Federico Cabiddu
4
5   <federico.cabiddu@gmail.com>
6
7Edited by
8
9Federico Cabiddu
10
11   <federico.cabiddu@gmail.com>
12
13   Copyright © 2015 Federico Cabiddu
14     __________________________________________________________________
15
16   Table of Contents
17
18   1. Admin Guide
19
20        1. Overview
21        2. Dependencies
22
23              2.1. Kamailio modules
24              2.2. External libraries or applications
25
26        3. Parameters
27
28              3.1. hash_size (integer)
29              3.2. use_domain (integer)
30
31        4. Functions
32
33              4.1. ts_store([uri])
34              4.2. ts_append(domain, ruri)
35              4.3. ts_append_to(tindex, tlabel, domain, [uri])
36
37        5. RPC Commands
38
39              5.1. ts.dump
40              5.2. ts.lookup
41
42        6. Statistics
43
44              6.1. stored_ruris
45              6.2. stored_transactions
46              6.3. added_branches
47              6.4. total_ruris
48              6.5. total_transactions
49
50   List of Examples
51
52   1.1. Set hash_size parameter
53   1.2. Set use_domain parameter
54   1.3. ts_store usage
55   1.4. ts_append usage
56   1.5. ts_append_to usage
57
58Chapter 1. Admin Guide
59
60   Table of Contents
61
62   1. Overview
63   2. Dependencies
64
65        2.1. Kamailio modules
66        2.2. External libraries or applications
67
68   3. Parameters
69
70        3.1. hash_size (integer)
71        3.2. use_domain (integer)
72
73   4. Functions
74
75        4.1. ts_store([uri])
76        4.2. ts_append(domain, ruri)
77        4.3. ts_append_to(tindex, tlabel, domain, [uri])
78
79   5. RPC Commands
80
81        5.1. ts.dump
82        5.2. ts.lookup
83
84   6. Statistics
85
86        6.1. stored_ruris
87        6.2. stored_transactions
88        6.3. added_branches
89        6.4. total_ruris
90        6.5. total_transactions
91
921. Overview
93
94   This module provides transaction storage for the Kamailio SIP Server
95   Platform. It stores in an internal table transactions for a Request-URI
96   (R-URI) and add branches to them later if new contacts for the AOR are
97   added.
98
99   For each message, the modules stores “Request-URI” (“R-URI”), URI and
100   the internal transaction index and label.
101
102   When a transaction is destroyed by the TM module, it is removed from
103   the module's table too.
104
1052. Dependencies
106
107   2.1. Kamailio modules
108   2.2. External libraries or applications
109
1102.1. Kamailio modules
111
112   The following modules must be loaded before this module:
113     * REGISTRAR--registrar module-- used to lookup for new contacts and
114       update the dset for the r-uri.
115     * TM--transaction module-- used to send SIP requests.
116     * SL
117
1182.2. External libraries or applications
119
120   The following libraries or applications must be installed before
121   running Kamailio with this module:
122     * none.
123
1243. Parameters
125
126   3.1. hash_size (integer)
127   3.2. use_domain (integer)
128
1293.1. hash_size (integer)
130
131   The size of the hash table internally used to keep the transaction. A
132   larger table is much faster but consumes more memory. The hash size
133   must be a power of two, otherwise it will be rounded down to the
134   nearest power of two.
135
136   Default value is “2048”.
137
138   Example 1.1. Set hash_size parameter
139...
140modparam("tsilo", "hash_size", 1024)
141...
142
1433.2. use_domain (integer)
144
145   Specify if the domain part of the URI should be also saved and used for
146   storing and retrieving users' transactions. Useful in multi domain
147   scenarios. Non 0 value means true.
148
149   Default value is “0”.
150
151   Example 1.2. Set use_domain parameter
152...
153modparam("tsilo", "use_domain", 1)
154...
155
1564. Functions
157
158   4.1. ts_store([uri])
159   4.2. ts_append(domain, ruri)
160   4.3. ts_append_to(tindex, tlabel, domain, [uri])
161
1624.1. ts_store([uri])
163
164   The method stores uri, tindex and tlabel of the current transaction. If
165   the uri parameter is missing, then the value is taken from r-uri. The
166   uri parameter can contain variables.
167
168   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
169
170   Example 1.3. ts_store usage
171...
172if (is_method("INVITE")) {
173    if (t_newtran()) {
174        ts_store();
175        # t_store("sip:alice@$td");
176    }
177}
178...
179
1804.2. ts_append(domain, ruri)
181
182   The method add branches to all the stored transactions for the SIP ruri
183   passed as parameter, performing a contact lookup on the table specified
184   by the domain parameter. The method should be called when a REGISTER
185   request is received.
186
187   Meaning of the parameters is as follows:
188     * domain - Name of table that should be used for looking up new
189       contacts for r-uri.
190     * ruri - The r-uri for which we want to check existing transactions
191       and add them new branches. Can be a static string value or a
192       dynamic string with pseudo-variables.
193
194   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
195
196   Example 1.4. ts_append usage
197...
198if (is_method("REGISTER")) {
199        ts_append("location", "$tu");
200}
201...
202
2034.3. ts_append_to(tindex, tlabel, domain, [uri])
204
205   The method add branches to the transaction identified by tindex and
206   tlabel, performing a contacts lookup on the table specified by the
207   domain parameter. The method should be called when a REGISTER request
208   is received.
209
210   Meaning of the parameters is as follows:
211     * tindex - internal index of transaction. Can be an integer or a
212       pseudo-variable.
213     * tlabel - internal label of transaction. Can be an integer or a
214       pseudo-variable.
215     * domain - Name of table that should be used for looking up new
216       contacts for r-uri.
217     * uri (optional) - uri for which to do lookup for new destinations.
218
219   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
220
221   Example 1.5. ts_append_to usage
222...
223if (is_method("REGISTER")) {
224        $var(tindex) = ...
225        $var(tlabel) = ...
226        ts_append_to("$var(tindex)", "$var(tlabel", "location");
227}
228...
229
2305. RPC Commands
231
232   5.1. ts.dump
233   5.2. ts.lookup
234
2355.1. ts.dump
236
237   Dumps the content of the TSILO table
238
239   Name: ts.dump
240
241   RPC Command Format:
242                        kamcmd ts.dump
243
2445.2. ts.lookup
245
246   Dumps the transactions stored for the given RURI
247
248   Name: ts.lookup
249
250   RPC Command Format:
251                        kamcmd ts.lookup sip:abcd@example.com
252
2536. Statistics
254
255   6.1. stored_ruris
256   6.2. stored_transactions
257   6.3. added_branches
258   6.4. total_ruris
259   6.5. total_transactions
260
2616.1. stored_ruris
262
263   Number of ruris currently stored in the TSILO table.
264
2656.2. stored_transactions
266
267   Number of transactions currently stored in the TSILO table.
268
2696.3. added_branches
270
271   Total number of added branches from the startup.
272
2736.4. total_ruris
274
275   Total number of stored ruris from the startup.
276
2776.5. total_transactions
278
279   Total number of stored transactions from the startup.
280