Debian Codegraph @

src/modules/xmpp/README

raw
1 xmpp Module
2
3 Andreea Spirea
4
5 Daniel-Constantin Mierla
6
7 <[email protected]>
8
9 Edited by
10
11 Andreea Spirea
12
13 Copyright © 2006 Voice Sistem SRL
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. backend (string)
29 3.2. domain_separator (string)
30 3.3. gateway_domain (string)
31 3.4. xmpp_domain (string)
32 3.5. xmpp_host (string)
33 3.6. xmpp_port (integer)
34 3.7. xmpp_password (string)
35 3.8. outbound_proxy (string)
36 3.9. gwmap (string)
37
38 4. Functions
39
40 4.1. xmpp_send_message()
41
42 5. Configuration
43
44 List of Examples
45
46 1.1. Set backend parameter
47 1.2. Set domain_separator parameter
48 1.3. Set gateway_domain parameter
49 1.4. Set xmpp_domain parameter
50 1.5. Set xmpp_host parameter
51 1.6. Set xmpp_port parameter
52 1.7. Set xmpp_password parameter
53 1.8. Set outbound_proxy parameter
54 1.9. Set gwmap parameter
55 1.10. xmpp_send_message() usage
56
57 Chapter 1. Admin Guide
58
59 Table of Contents
60
61 1. Overview
62 2. Dependencies
63
64 2.1. Kamailio Modules
65 2.2. External Libraries or Applications
66
67 3. Parameters
68
69 3.1. backend (string)
70 3.2. domain_separator (string)
71 3.3. gateway_domain (string)
72 3.4. xmpp_domain (string)
73 3.5. xmpp_host (string)
74 3.6. xmpp_port (integer)
75 3.7. xmpp_password (string)
76 3.8. outbound_proxy (string)
77 3.9. gwmap (string)
78
79 4. Functions
80
81 4.1. xmpp_send_message()
82
83 5. Configuration
84
85 1. Overview
86
87 This module is a gateway between Kamailio and a XMPP/Jabber server. It
88 enables the exchange of instant messages between SIP clients and
89 XMPP(jabber) clients.
90
91 The module can be used in two different modes:
92 * XMPP Component Mode. In this mode, Kamailio connects to an XMPP
93 server using the standardized XMPP component interface, extending
94 your XMPP services. The connection is done over TCP/IP with
95 authorization.
96 * XMPP Server. In this mode, the Kamailio XMPP module is a
97 stand-alone XMPP server connector, with no requirement for another
98 XMPP server in the system. This server uses XMPP S2S (Server to
99 Server) connections to connect to other XMPP servers or receive
100 connections from other servers. NOTE: this is limited
101 implementation of a XMPP server, it does not support SRV or TLS so
102 far. Also, in this mode it cannot get XMPP clients connected, only
103 XMPP servers (in other words, you cannot use it to replace an XMPP
104 full server implementation). This mode is in beta stage for the
105 moment.
106
107 In the component mode, you need a local XMPP server (recommended
108 Jabberd2). The XMPP module will connect by using TCP/IP connection to
109 the local jabber server. The documentation and the source for Jabberd
110 server are located at the following link:
111 http://jabberd.jabberstudio.org/2/#download
112
113 After you have a running XMPP server, what you need to do is set the
114 following parameters in the Kamailio configuration file:
115 * gateway_domain, xmpp_domain (which can be the same as
116 gateway_domain) and xmpp_host, which are explained in the Exported
117 Parameters section;
118 * listen = your ip;
119 * alias=Kamailio SIP domain and alias=gateway domain;
120 * in the following section of the configuration file, change to your
121 gateway domain:
122
123 ### ---8<--- cut here ---8<--- ###
124 if ($rd =="sip-xmpp.kamailio.org") {
125 if (!t_newtran()) {
126 sl_reply_error();
127 ...........
128
129 * You can also define a password for the XMPP Component connection to
130 the Jabber server, which must be the same as the xmpp_password
131 parameter.
132
133 A use case, for the component-mode, would look like this:
134 * Kamailio is hosting the sip-server.kamailio.org SIP domain
135 * The gateway SIP domain is sip-xmpp.kamailio.org
136 * The XMPP server is hosting the XMPP domain xmpp.kamailio.org
137 * The Component is hosting the XMPP domain xmpp-sip.kamailio.org
138
139 In the XMPP stand-alone server mode, the XMPP module is a minimal
140 XMPP/Jabber server. In this mode, another Jabber server is not needed.
141 The gateway will connect to other XMPP servers based on the JID domain
142 and by using the standardized XMPP S2S protocol.
143
144 If you want to change to server-mode, you have to change the "backend"
145 parameter, as shown in the Exported Parameters section, from
146 "component" to "server".
147
148 A use case, for the server-mode, would look like this:
149 * Kamailio is hosting the SIP domain sip-server.kamailio.org
150 * The gateway is hosting the SIP domain sip-xmpp.kamailio.org;
151 * The "XMPP server" is running on xmpp-sip.kamailio.org.
152
153 Unless 'gwmap' parameter is set, in both modes (server or component),
154 the destination address must have the same pattern:
155
156 “sip:username<delim>jabber_server@gateway_domain”
157
158 From a jabber client's point of view, the destination will look like:
159
160 “sip_username<delim>sip_domain@xmpp_domain”
161
162 'delim' is a character that can be set via 'domain_separator'
163 parameter.
164
165 If 'gwmap' parameter is used, then the addresses are not encoding the
166 domains in the username part. They are going to be straight
167 'username@domain' always.
168
169 2. Dependencies
170
171 2.1. Kamailio Modules
172 2.2. External Libraries or Applications
173
174 2.1. Kamailio Modules
175
176 The following modules must be loaded before this module:
177 * requires 'tm' module.
178
179 2.2. External Libraries or Applications
180
181 The following libraries or applications must be installed before
182 running Kamailio with this module loaded:
183 * expat - used for parsing/building XML. Linux package:
184 libexpat1-devel
185
186 3. Parameters
187
188 3.1. backend (string)
189 3.2. domain_separator (string)
190 3.3. gateway_domain (string)
191 3.4. xmpp_domain (string)
192 3.5. xmpp_host (string)
193 3.6. xmpp_port (integer)
194 3.7. xmpp_password (string)
195 3.8. outbound_proxy (string)
196 3.9. gwmap (string)
197
198 3.1. backend (string)
199
200 The mode you are using the module; it can be either "component" or
201 "server".
202
203 Default value is "component".
204
205 Example 1.1. Set backend parameter
206 ...
207 modparam("xmpp", "backend", "server")
208 ...
209
210 3.2. domain_separator (string)
211
212 In the destination address we need an extra character as a domain
213 separator, apart from @. The address of the XMPP(jabber) client looks
214 like this:
215 "sip:username<domain_separator>jabber_server@gateway_sip_domain". The
216 address of a SIP client has the following pattern :
217 "sip_username<domain_separator>sip_domain@gateway_xmpp_domain"; A
218 common used character in XMPP transports is "%".
219
220 Default value is "*".
221
222 Example 1.2. Set domain_separator parameter
223 ...
224 modparam("xmpp", "domain_separator", "%")
225 ...
226
227 3.3. gateway_domain (string)
228
229 The domain of the SIP-to-XMPP gateway - it has to be in DNS or SIP UA
230 has to use outbound proxy to SIP-to-XMPP gateway IP address. It has to
231 be used as domain in the destination address of the messages sent by
232 SIP users to XMPP users:
233 "sip:username<delim>jabber_server@gateway_domain".
234
235 Default value is "sip-xmpp.example.org".
236
237 Example 1.3. Set gateway_domain parameter
238 ...
239 modparam("xmpp", "gateway_domain", "sip-xmpp.kamailio.org")
240 ...
241
242 3.4. xmpp_domain (string)
243
244 The XMPP domain of the component or the server, depending on the mode.
245 It can be the same as the gateway_domain. For a server DNS name, you
246 have to add _xmpp-server._tcp SRV records in your DNS zone to enable
247 connections from other XMPP servers.
248
249 Default value is "sip-xmpp.example.org".
250
251 Example 1.4. Set xmpp_domain parameter
252 ...
253 modparam("xmpp", "xmpp_domain", "xmpp-sip.kamailio.org")
254 ...
255
256 3.5. xmpp_host (string)
257
258 The IP address or the hostname for the local XMPP/Jabber server to
259 connect to when the backend is set to "component". For server mode,
260 this is the IP address the XMPP module binds to listen for connections
261 coming from other XMPP servers.
262
263 Default value is "xmpp.example.org".
264
265 Example 1.5. Set xmpp_host parameter
266 ...
267 modparam("xmpp", "xmpp_host", "xmpp.kamailio.org")
268 ...
269
270 3.6. xmpp_port (integer)
271
272 In component mode, this is the port the XMPP server component interface
273 listens to. In server mode, this is the port the module listens to.
274
275 Default value is "5347", if backend is set to "component" and "5269",
276 if backend is set to "server".
277
278 Example 1.6. Set xmpp_port parameter
279 ...
280 modparam("xmpp", "xmpp_port", 5269)
281 ...
282
283 3.7. xmpp_password (string)
284
285 The password of the local XMPP server.
286
287 This is the password for the component interface on the XMPP server,
288 when connecting as a component. Default password is "secret". When
289 connecting to jabberd2, you need to make sure this is the password
290 configured in the file "c2s.xml". This is how the default configuration
291 for the jabberd2 looks like:
292 <router>
293 ...............
294 <!-- Username/password to authenticate as --&gt;
295 <user>jabberd</user>; <!-- default: jabberd -->;
296 <pass>secret</pass>; <!-- default: secret -->;
297
298 Example 1.7. Set xmpp_password parameter
299 ...
300 modparam("xmpp", "xmpp_password", "secret")
301 ...
302
303 3.8. outbound_proxy (string)
304
305 The SIP address used as next hop when sending the message. Very useful
306 when using Kamailio with a domain name not in DNS, or when using a
307 separate Kamailio instance for XMPP processing. If not set, the message
308 will be sent to the address in destination URI.
309
310 Default value is NULL.
311
312 Example 1.8. Set outbound_proxy parameter
313 ...
314 modparam("xmpp", "outbound_proxy", "sip:kamailio.org;transport=tcp")
315 ...
316
317 3.9. gwmap (string)
318
319 Set the mappings between SIP and XMPP domains. This parameter can be
320 set many times, adding more SIP-XMPP domain mappings. Its value has to
321 be a list of tokens like 'sipdomain=xmppdomain', separated by ';'
322 (e.g., 'sipdomain1=xmppdomain1;sipdomain2=xmppdomain2'.
323
324 When this parameter is set, the URI encoding based on
325 'domain_separator' is no longer enabled. The module will use only
326 addresses in the format 'username@domain'. If the source or destination
327 address does not match a domain in gwmap, then the domain value is
328 preserved when sending to the other protocol.
329
330 Default value is NULL.
331
332 Example 1.9. Set gwmap parameter
333 ...
334 modparam("xmpp", "gwmap", "sip.kamailio.org=xmpp.kamailio.org;abc.com=xyz.com")
335 modparam("xmpp", "gwmap", "kamailio.net")
336 ...
337
338 Based on the above parameter values, if there is a SIP message from
339 'sip:[email protected]' going to 'sip:[email protected]', the XMPP
340 message to be sent is from '[email protected]' to '[email protected]'.
341
342 4. Functions
343
344 4.1. xmpp_send_message()
345
346 4.1. xmpp_send_message()
347
348 Converts SIP messages to XMPP(jabber) messages, in order to be relayed
349 to a XMPP(jabber) client.
350
351 Example 1.10. xmpp_send_message() usage
352 ...
353 xmpp_send_message();
354 ...
355
356 5. Configuration
357
358 Next is presented a sample configuration file one can use to implement
359 a standalone SIP-to-XMPP gateway. You can run an instance of Kamailio
360 on a separate machine or on different port with the following config,
361 and have the main SIP server configured to forward all SIP requests for
362 XMPP world to it.
363 ....
364 #
365 # $Id$
366 #
367 # simple quick-start config script for XMPP GW
368 #
369 # make sure in your main SIP server that you send
370 # only the adequate SIP MESSAGES to XMPP GW
371 #
372 #
373 # ----------- global configuration parameters ------------------------
374
375 debug=9 # debug level (cmd line: -dddddddddd)
376 fork=no
377 log_stderror=yes # (cmd line: -E)
378
379 /* Uncomment these lines to enter debugging mode
380 fork=no
381 log_stderror=yes
382 */
383
384 check_via=no # (cmd. line: -v)
385 dns=no # (cmd. line: -r)
386 rev_dns=no # (cmd. line: -R)
387 children=4
388
389 listen=udp:10.10.10.10:5076
390 alias=sip-xmpp.kamailio.org
391
392 # ------------------ module loading ----------------------------------
393
394 loadmodule "sl.so"
395 loadmodule "tm.so"
396 loadmodule "rr.so"
397 loadmodule "maxfwd.so"
398 loadmodule "textops.so"
399 loadmodule "jsonrpcs.so"
400
401
402 # XMPP
403 loadmodule "xmpp.so"
404
405 modparam("xmpp", "domain_separator", "*")
406 modparam("xmpp", "gateway_domain", "sip-xmpp.kamailio.org")
407 modparam("xmpp", "xmpp_domain", "xmpp-sip.kamailio.org")
408 modparam("xmpp", "xmpp_host", "xmpp.kamailio.org")
409
410 modparam("xmpp", "backend", "server")
411 # modparam("xmpp", "backend", "component")
412
413 # ----------------- setting module-specific parameters ---------------
414
415 # -- usrloc params --
416
417 # -- rr params --
418 # add value to ;lr param to make some broken UAs happy
419 modparam("rr", "enable_full_lr", 1)
420
421 # ------------------------- request routing logic -------------------
422
423 # main routing logic
424
425 route{
426
427 # initial sanity checks -- messages with
428 # max_forwards==0, or excessively long requests
429 if (!mf_process_maxfwd_header("10")) {
430 sl_send_reply("483","Too Many Hops");
431 exit;
432 };
433
434 if (msg:len >= 2048 ) {
435 sl_send_reply("513", "Message too big");
436 exit;
437 };
438
439 ### absorb retransmissions ###
440 if (!t_newtran()) {
441 sl_reply_error();
442 return;
443 }
444 if (method == "MESSAGE") {
445 log("*** xmpp-handled MESSAGE message.\n");
446 if (xmpp_send_message()) {
447 t_reply("200", "Accepted");
448 } else {
449 t_reply("404", "Not found");
450 }
451 return;
452 }
453
454 log("*** xmpp: unhandled message type\n");
455 t_reply("503", "Service unavailable");
456 return;
457 }
458
459
460 ....