Debian Codegraph @

src/modules/path/README

raw
1 path Module
2
3 Andreas Granig
4
5 Inode GmbH
6
7 Edited by
8
9 Andreas Granig
10
11 Richard Fuchs
12
13 Copyright © 2006 Inode GmbH
14 __________________________________________________________________
15
16 Table of Contents
17
18 1. Admin Guide
19
20 1. Overview
21
22 1.1. Path Insertion For Registrations
23 1.2. Outbound routing to NAT'ed UACs
24
25 2. Dependencies
26
27 2.1. Kamailio Modules
28 2.2. External Libraries or Applications
29
30 3. Parameters
31
32 3.1. use_received (int)
33 3.2. received_format (int)
34 3.3. received_name (str)
35 3.4. enable_r2 (int)
36 3.5. sockname_mode (int)
37
38 4. Functions
39
40 4.1. add_path()
41 4.2. add_path(user)
42 4.3. add_path(user, parameters)
43 4.4. add_path_received()
44 4.5. add_path_received(user)
45 4.6. add_path_received(user, parameters)
46
47 List of Examples
48
49 1.1. Add Supported header
50 1.2. Set use_received parameter
51 1.3. Set received_format parameter
52 1.4. Set received_name parameter
53 1.5. Set enable_r2 parameter
54 1.6. Set sockname_mode parameter
55 1.7. add_path usage
56 1.8. add_path(user) usage
57 1.9. add_path(user, parameters) usage
58 1.10. add_path_received() usage
59 1.11. add_path_received(user) usage
60 1.12. add_path_received(user, parameters) usage
61
62 Chapter 1. Admin Guide
63
64 Table of Contents
65
66 1. Overview
67
68 1.1. Path Insertion For Registrations
69 1.2. Outbound routing to NAT'ed UACs
70
71 2. Dependencies
72
73 2.1. Kamailio Modules
74 2.2. External Libraries or Applications
75
76 3. Parameters
77
78 3.1. use_received (int)
79 3.2. received_format (int)
80 3.3. received_name (str)
81 3.4. enable_r2 (int)
82 3.5. sockname_mode (int)
83
84 4. Functions
85
86 4.1. add_path()
87 4.2. add_path(user)
88 4.3. add_path(user, parameters)
89 4.4. add_path_received()
90 4.5. add_path_received(user)
91 4.6. add_path_received(user, parameters)
92
93 1. Overview
94
95 1.1. Path Insertion For Registrations
96 1.2. Outbound routing to NAT'ed UACs
97
98 This module is designed to be used at intermediate sip proxies like
99 loadbalancers in front of registrars and proxies. It provides functions
100 for inserting a Path header including a parameter for passing forward
101 the received-URI of a registration to the next hop. It also provides a
102 mechanism for evaluating this parameter in subsequent requests and to
103 set the destination URI according to it.
104
105 1.1. Path Insertion For Registrations
106
107 For registrations in a scenario like “[UAC] -> [P1] -> [REG]”, the
108 "path" module can be used at the intermediate proxy P1 to insert a Path
109 header into the message before forwarding it to the registrar REG. Two
110 functions can be used to achieve this:
111 * add_path(...) adds a Path header in the form of “Path:
112 <sip:1.2.3.4;lr>” to the message using the address of the outgoing
113 interface. A port is only added if it's not the default port 5060.
114 If a username is passed to the function, it is also included in the
115 Path URI, like “Path: <sip:[email protected];lr>”.
116 * add_path_received(...) also add a Path header in the same form as
117 above, but also adds a parameter indicating the received-URI of the
118 message, like “Path: <sip:1.2.3.4;received=sip:2.3.4.5:1234;lr>”.
119 This is especially useful if the proxy does NAT detection and wants
120 to pass the NAT'ed address to the registrar.
121 If the function is called with a username, it's included in the
122 Path URI too.
123
124 Note that some SIP registrars may check if header Supported includes
125 'path'. It can be added in kamailio.cfg using append_hf() from textops
126 module.
127
128 Example 1.1. Add Supported header
129 ...
130 append_hf("Supported: path\r\n");
131 ...
132
133 1.2. Outbound routing to NAT'ed UACs
134
135 If the NAT'ed address of an UAC is passed to the registrar, the
136 registrar routes back subsequent requests using the Path header of the
137 registration as Route header of the current request. If the
138 intermediate proxy had inserted a Path header including the “received”
139 parameter during the registration, this parameter will show up in the
140 Route header of the new request as well, allowing the intermediate
141 proxy to route to this address instead of the one propagated in the
142 Route URI for tunneling through NAT. This behaviour can be activated by
143 setting the module parameter “use_received”.
144
145 2. Dependencies
146
147 2.1. Kamailio Modules
148 2.2. External Libraries or Applications
149
150 2.1. Kamailio Modules
151
152 The following modules must be loaded before this module:
153 * The "rr" module is needed for outbound routing according to the
154 “received” parameter.
155 * The "outbound" module is needed for outbound routing as per RFC
156 5626.
157
158 2.2. External Libraries or Applications
159
160 The following libraries or applications must be installed before
161 running Kamailio with this module loaded:
162 * None.
163
164 3. Parameters
165
166 3.1. use_received (int)
167 3.2. received_format (int)
168 3.3. received_name (str)
169 3.4. enable_r2 (int)
170 3.5. sockname_mode (int)
171
172 3.1. use_received (int)
173
174 If set to 1, the “received” parameter of the first Route URI is
175 evaluated and used as destination-URI if present.
176
177 Default value is 0.
178
179 Example 1.2. Set use_received parameter
180 ...
181 modparam("path", "use_received", 1)
182 ...
183
184 3.2. received_format (int)
185
186 If set to 0, the “received” parameter value will be in the escaped SIP
187 URI format.
188
189 If set to 1, the “received” parameter value will be in the same format
190 as the “alias” parameter added by set_contact_alias() from “nathelper”
191 module (i.e., “ip~port~protid”). This is a solution with some SIP
192 applications that incorrectly match the transport from received
193 parameter instead of the one from the SIP URI.
194
195 Default value is 0.
196
197 Example 1.3. Set received_format parameter
198 ...
199 modparam("path", "received_format", 1)
200 ...
201
202 3.3. received_name (str)
203
204 Set the name of the header parameter to add the “received” value.
205
206 Default value is "received".
207
208 Example 1.4. Set received_name parameter
209 ...
210 modparam("path", "received_name", "rcv")
211 ...
212
213 3.4. enable_r2 (int)
214
215 If set to 1, the module will add two Path headers, similar to the
216 double Record-Route done by rr module. One Path headers corresponds to
217 incoming network socket and the other to outgoing network socket. The
218 URIs in the Path headers will have the 'r2=on' parameter as well.
219
220 Note: if enabled, the module adds the two Path headers even when the
221 incoming socket is the same as outgoing socket. Improvements to skip
222 the second Path header in this case may be introduced in the future,
223 meanwhile, if you need to enable this parameter but also deal with same
224 socket routing, use 'insert_hf("Path: <$Ru>\r\n")'.
225
226 Default value is 0.
227
228 Example 1.5. Set enable_r2 parameter
229 ...
230 modparam("path", "enable_r2", 1)
231 ...
232
233 3.5. sockname_mode (int)
234
235 If set to 1, the Path URI is built to contain socket name in 'sn'
236 parameter.
237
238 Default value is 0.
239
240 Example 1.6. Set sockname_mode parameter
241 ...
242 modparam("path", "sockname_mode", 1)
243 ...
244
245 4. Functions
246
247 4.1. add_path()
248 4.2. add_path(user)
249 4.3. add_path(user, parameters)
250 4.4. add_path_received()
251 4.5. add_path_received(user)
252 4.6. add_path_received(user, parameters)
253
254 4.1. add_path()
255
256 This function is used to insert a Path header in the form “Path:
257 <sip:1.2.3.4;lr>”, where “1.2.3.4” is the address of the outgoing
258 interface.
259
260 If the “outbound” module was loaded before this module, and outbound is
261 required for this request, the header will be in the form “Path:
262 <sip:[email protected];lr;ob>”, where “flowtoken” is the RFC 5626
263 flow-token that can be used to identify the source and local address
264 and transport the request was received on, and where “1.2.3.4” is the
265 address of the outgoing interface.
266
267 This function can be used from REQUEST_ROUTE.
268
269 Example 1.7. add_path usage
270 ...
271 if (!add_path()) {
272 sl_send_reply("503", "Internal Path Error");
273 ...
274 };
275 ...
276
277 4.2. add_path(user)
278
279 This function adds a Path header in the form “Path:
280 <sip:[email protected];lr>”.
281
282 Meaning of the parameters is as follows:
283 * user - The username to be inserted as user part. SPVE is supported.
284
285 This function can be used from REQUEST_ROUTE.
286
287 Example 1.8. add_path(user) usage
288 ...
289 if (!add_path("loadbalancer")) {
290 sl_send_reply("503", "Internal Path Error");
291 ...
292 };
293 ...
294
295 4.3. add_path(user, parameters)
296
297 This function adds a Path header in the form “Path:
298 <sip:[email protected];lr>” and appends the given parameters as additional
299 URI parameters.
300
301 Meaning of the parameters is as follows:
302 * user - The username to be inserted as user part. SPVE is supported.
303 * parameters - Additional URI parameters to be appended to the URI.
304 The semicolon separator is added automatically. The script writer
305 is responsible for proper URI escaping. SPVE is supported.
306
307 This function can be used from REQUEST_ROUTE.
308
309 Example 1.9. add_path(user, parameters) usage
310 ...
311 if (!add_path("loadbalancer", "ob")) {
312 sl_send_reply("503", "Internal Path Error");
313 ...
314 };
315 ...
316
317 4.4. add_path_received()
318
319 This function adds a Path header in the form “Path:
320 <sip:1.2.3.4;received=sip:2.3.4.5:1234;lr>”, setting its own outgoing
321 address as domain-part, and the address the request has been received
322 from as received-parameter.
323
324 If the “outbound” module was loaded before this module, and outbound is
325 required for this request, the header will be in the form “Path:
326 <sip:[email protected];lr;received=sip:2.3.4.5:1234;ob>”, where
327 “flowtoken” is the RFC 5626 flow-token that can be used to identify the
328 source and local address and transport the request was received on, and
329 where “1.2.3.4” is the address of the outgoing interface.
330
331 This function can be used from REQUEST_ROUTE.
332
333 Example 1.10. add_path_received() usage
334 ...
335 if (!add_path_received()) {
336 sl_send_reply("503", "Internal Path Error");
337 ...
338 };
339 ...
340
341 4.5. add_path_received(user)
342
343 This function adds a Path header in the form “Path:
344 <sip:[email protected];received=sip:2.3.4.5:1234;lr>”, setting 'user' as
345 username part of address, its own outgoing address as domain-part, and
346 the address the request has been received from as received-parameter.
347
348 This function can be used from REQUEST_ROUTE.
349
350 Example 1.11. add_path_received(user) usage
351 ...
352 if (!add_path_received("inbound")) {
353 sl_send_reply("503", "Internal Path Error");
354 ...
355 };
356 ...
357
358 4.6. add_path_received(user, parameters)
359
360 This function adds a Path header in the form “Path:
361 <sip:[email protected];received=sip:2.3.4.5:1234;lr>”, setting 'user' as
362 username part of address, its own outgoing address as domain-part, and
363 the address the request has been received from as received-parameter.
364
365 This function can be used from REQUEST_ROUTE.
366
367 Example 1.12. add_path_received(user, parameters) usage
368 ...
369 if (!add_path_received("inbound", "ob")) {
370 sl_send_reply("503", "Internal Path Error");
371 ...
372 };
373 ...