| 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 --> |
| 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 |
.... |