Debian Codegraph @

src/modules/tsilo/README

raw
1 TSILO Module
2
3 Federico Cabiddu
4
5 <[email protected]>
6
7 Edited by
8
9 Federico Cabiddu
10
11 <[email protected]>
12
13 Donat Zenichev
14
15 <[email protected]>
16
17 Copyright © 2015 Federico Cabiddu
18 __________________________________________________________________
19
20 Table of Contents
21
22 1. Admin Guide
23
24 1. Overview
25 2. Dependencies
26
27 2.1. Kamailio modules
28 2.2. External libraries or applications
29
30 3. Parameters
31
32 3.1. hash_size (integer)
33 3.2. use_domain (integer)
34
35 4. Functions
36
37 4.1. ts_store([uri])
38 4.2. ts_append(domain, ruri)
39 4.3. ts_append_by_contact(domain, ruri [, contact])
40 4.4. ts_append_to(tindex, tlabel, domain, [uri])
41 4.5. ts_append_branches(uri)
42
43 5. RPC Commands
44
45 5.1. ts.dump
46 5.2. ts.lookup
47
48 6. Statistics
49
50 6.1. stored_ruris
51 6.2. stored_transactions
52 6.3. added_branches
53 6.4. total_ruris
54 6.5. total_transactions
55
56 List of Examples
57
58 1.1. Set hash_size parameter
59 1.2. Set use_domain parameter
60 1.3. ts_store usage
61 1.4. ts_append usage
62 1.5. ts_append_by_contact usage
63 1.6. ts_append_to usage
64 1.7. ts_append_branches usage
65
66 Chapter 1. Admin Guide
67
68 Table of Contents
69
70 1. Overview
71 2. Dependencies
72
73 2.1. Kamailio modules
74 2.2. External libraries or applications
75
76 3. Parameters
77
78 3.1. hash_size (integer)
79 3.2. use_domain (integer)
80
81 4. Functions
82
83 4.1. ts_store([uri])
84 4.2. ts_append(domain, ruri)
85 4.3. ts_append_by_contact(domain, ruri [, contact])
86 4.4. ts_append_to(tindex, tlabel, domain, [uri])
87 4.5. ts_append_branches(uri)
88
89 5. RPC Commands
90
91 5.1. ts.dump
92 5.2. ts.lookup
93
94 6. Statistics
95
96 6.1. stored_ruris
97 6.2. stored_transactions
98 6.3. added_branches
99 6.4. total_ruris
100 6.5. total_transactions
101
102 1. Overview
103
104 This module provides transaction storage for the Kamailio SIP Server
105 Platform. It stores in an internal table transactions for a Request-URI
106 (R-URI) and adds branches to them later if new contacts for the AOR are
107 added.
108
109 For each message, the module stores “Request-URI” (“R-URI”), URI and
110 the internal transaction index and label.
111
112 When a transaction is destroyed by the TM module, it is removed from
113 the module's table too.
114
115 2. Dependencies
116
117 2.1. Kamailio modules
118 2.2. External libraries or applications
119
120 2.1. Kamailio modules
121
122 The following modules must be loaded before this module:
123 * REGISTRAR--registrar module-- used to lookup for new contacts and
124 update the dset for the r-uri.
125 * TM--transaction module-- used to send SIP requests.
126 * SL
127
128 2.2. External libraries or applications
129
130 The following libraries or applications must be installed before
131 running Kamailio with this module:
132 * none.
133
134 3. Parameters
135
136 3.1. hash_size (integer)
137 3.2. use_domain (integer)
138
139 3.1. hash_size (integer)
140
141 The size of the hash table internally used to keep the transaction. A
142 larger table is much faster but consumes more memory. The hash size
143 must be a power of two, otherwise it will be rounded down to the
144 nearest power of two.
145
146 Default value is “2048”.
147
148 Example 1.1. Set hash_size parameter
149 ...
150 modparam("tsilo", "hash_size", 1024)
151 ...
152
153 3.2. use_domain (integer)
154
155 Specify if the domain part of the URI should be also saved and used for
156 storing and retrieving users' transactions. Useful in multi domain
157 scenarios. Non 0 value means true.
158
159 Default value is “0”.
160
161 Example 1.2. Set use_domain parameter
162 ...
163 modparam("tsilo", "use_domain", 1)
164 ...
165
166 4. Functions
167
168 4.1. ts_store([uri])
169 4.2. ts_append(domain, ruri)
170 4.3. ts_append_by_contact(domain, ruri [, contact])
171 4.4. ts_append_to(tindex, tlabel, domain, [uri])
172 4.5. ts_append_branches(uri)
173
174 4.1. ts_store([uri])
175
176 The method stores uri, tindex and tlabel of the current transaction. If
177 the uri parameter is missing, then the value is taken from r-uri. The
178 uri parameter can contain variables.
179
180 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
181
182 Example 1.3. ts_store usage
183 ...
184 if (is_method("INVITE")) {
185 if (t_newtran()) {
186 ts_store();
187 # ts_store("sip:alice@$td");
188 }
189 }
190 ...
191
192 4.2. ts_append(domain, ruri)
193
194 The method add branches to all the stored transactions for the SIP ruri
195 passed as parameter, performing a contact lookup on the table specified
196 by the domain parameter. The method should be called when a REGISTER
197 request is received.
198
199 Meaning of the parameters is as follows:
200 * domain - Name of table that should be used for looking up new
201 contacts for r-uri.
202 * ruri - The r-uri for which we want to check existing transactions
203 and add them new branches. Can be a static string value or a
204 dynamic string with pseudo-variables.
205
206 Return codes:
207 * 1 - branches added.
208 -1 - an internal error has produced (parsing error, memory error).
209 -2 - no records found for the r-uri.
210
211 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
212
213 Example 1.4. ts_append usage
214 ...
215 if (is_method("REGISTER")) {
216 ts_append("location", "$tu");
217 }
218 ...
219
220 4.3. ts_append_by_contact(domain, ruri [, contact])
221
222 Has almost the same intention as the ts_append(), but gives a
223 possibility to append branches only for a specific location record
224 (Contact URI). The contact's URI value can be either taken from the
225 currently processed REGISTER or (optionally) given as a third
226 parameter. If the Contact URI for a lookup is given as the parameter,
227 it is possible to provide it as a pseudo-variable. The contact lookup
228 is performed on the table specified by the domain parameter. The method
229 should be called when a REGISTER request is received.
230
231 Meaning of the parameters is as follows:
232 * domain - Name of table that should be used for looking up new
233 contacts for r-uri.
234 * ruri - The r-uri for which we want to check existing transactions
235 and add them new branches. Can be a static string value or a
236 dynamic string with pseudo-variables.
237 * contact - Optional, a value of the location record (contact URI)
238 based on which to perform the branch appending. If not given, the
239 value will be taken from the currently processed REGISTER. If a
240 location lookup based on this Contact URI fails (no location record
241 found), then the branch append will not happen.
242
243 Return codes:
244 * 1 - branches added.
245 -1 - an internal error has produced (parsing error, memory error).
246 -2 - no records found for the r-uri.
247
248 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
249
250 Example 1.5. ts_append_by_contact usage
251 ...
252 if (is_method("REGISTER")) {
253 $var(formatted_ct) = $(x_hdr(Contact){nameaddr.uri});
254 ts_append_by_contact("location", "$tu", "$var(formatted_ct)");
255 }
256 ...
257
258 4.4. ts_append_to(tindex, tlabel, domain, [uri])
259
260 The method add branches to the transaction identified by tindex and
261 tlabel, performing a contacts lookup on the table specified by the
262 domain parameter. The method should be called when a REGISTER request
263 is received.
264
265 Meaning of the parameters is as follows:
266 * tindex - internal index of transaction. Can be an integer or a
267 pseudo-variable.
268 * tlabel - internal label of transaction. Can be an integer or a
269 pseudo-variable.
270 * domain - Name of table that should be used for looking up new
271 contacts for r-uri.
272 * uri (optional) - uri for which to do lookup for new destinations.
273
274 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
275
276 Example 1.6. ts_append_to usage
277 ...
278 if (is_method("REGISTER")) {
279 $var(tindex) = ...
280 $var(tlabel) = ...
281 ts_append_to("$var(tindex)", "$var(tlabel)", "location");
282 }
283 ...
284
285 4.5. ts_append_branches(uri)
286
287 Append the current internal branches to the transaction stored for the
288 uri.
289
290 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
291
292 Example 1.7. ts_append_branches usage
293 ...
294 ts_append_branches("sip:alice@$td");
295 ...
296
297 5. RPC Commands
298
299 5.1. ts.dump
300 5.2. ts.lookup
301
302 5.1. ts.dump
303
304 Dumps the content of the TSILO table
305
306 Name: ts.dump
307
308 RPC Command Format:
309 kamctl rpc ts.dump
310
311 5.2. ts.lookup
312
313 Dumps the transactions stored for the given RURI
314
315 Name: ts.lookup
316
317 RPC Command Format:
318 kamctl rpc ts.lookup sip:[email protected]
319
320 6. Statistics
321
322 6.1. stored_ruris
323 6.2. stored_transactions
324 6.3. added_branches
325 6.4. total_ruris
326 6.5. total_transactions
327
328 6.1. stored_ruris
329
330 Number of ruris currently stored in the TSILO table.
331
332 6.2. stored_transactions
333
334 Number of transactions currently stored in the TSILO table.
335
336 6.3. added_branches
337
338 Total number of added branches from the startup.
339
340 6.4. total_ruris
341
342 Total number of stored ruris from the startup.
343
344 6.5. total_transactions
345
346 Total number of stored transactions from the startup.