xmpp Module
Andreea Spirea
voice-system.ro
Edited by
Andreea Spirea
Copyright © 2006 voice-system.ro
__________________________________________________________
Table of Contents
1. User's Guide
1.1. Overview
1.2. Dependencies
1.2.1. OpenSER Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. backend(string)
1.3.2. domain_separator (string)
1.3.3. gateway_domain (string)
1.3.4. xmpp_domain (string)
1.3.5. xmpp_host (string)
1.3.6. xmpp_port (integer)
1.3.7. xmpp_password (string)
1.4. Exported Functions
1.4.1. xmpp_send_message()
1.5. Configuration
2. Developer's Guide
3. Frequently Asked Questions
List of Examples
1-1. Set backend parameter
1-2. Set domain_separator parameter
1-3. Set gateway_domain parameter
1-4. Set xmpp_domain parameter
1-5. Set xmpp_host parameter
1-6. Set xmpp_port parameter
1-7. Set xmpp_password parameter
1-8. xmpp_send_message() usage
__________________________________________________________
Chapter 1. User's Guide
1.1. Overview
This module is a gateway between Openser and a XMPP/Jabber
server. It enables the exchange of instant messages between SIP
clients and XMPP(jabber) clients.
The module can be used in two different modes:
* XMPP Component Mode. In this mode, OpenSER connects to an
XMPP server using the standardized XMPP component
interface, extending your XMPP services. The connection is
done over TCP/IP with authorization.
* XMPP Server. In this mode, the OpenSER XMPP module is a
stand-alone XMPP server, with no requirement for another
XMPP server in the system. This server uses XMPP S2S
(Server to Server) connections to connect to other XMPP
servers or receive connections from other servers. NOTE:
this is limited implementation of a XMPP server, it does
not support SRV or TLS so far. This mode is in beta stage
for the moment.
In the component mode, you need a local XMPP server
(recommended Jabberd2). The XMPP module will connect by using
TCP/IP connection to the local jabber server. The documentation
and the source for Jabberd server are located at the following
link: http://jabberd.jabberstudio.org/2/#download
After you have a running XMPP server, what you need to do is
set the following parameters in the Openser configuration file:
* gateway_domain, xmpp_domain (which can be the same as
gateway_domain) and xmpp_host, which are explained in the
Exported Parameters section;
* listen = your ip;
* alias=OpenSER SIP domain and alias=gateway domain;
* in the following section of the configuration file, change
to your gateway domain:
### ---8<--- cut here ---8<--- ###
if (avp_check("$rd", "eq/s:sip-xmpp.openser.org")) {
if (!t_newtran()) {
sl_reply_error();
...........
* you can also define a password for the XMPP Component
connection to the Jabber server, which must be the same as
the xmpp_password parameter.
A use case, for the component-mode, would look like this:
* Openser is hosting the sip-server.openser.org SIP domain
* The gateway SIP domain is sip-xmpp.openser.org
* The XMPP server is hosting the XMPP domain xmpp.openser.org
* The Component is hosting the XMPP domain
xmpp-sip.openser.org
In the XMPP stand-alone server mode, the XMPP module is a
minimal XMPP/Jabber server. In this mode, another Jabber server
is not needed. The gateway will connect to other XMPP servers
basaed on the JID domain and by using the standardized XMPP S2S
protocol.
If you want to change to server-mode, you have to change the
"backend" parameter, as shown in the Exported Parameters
section, from "component" to "server".
A use case, for the server-mode, would look like this:
* Openser is hosting the SIP domain sip-server.openser.org
* The gateway is hosting the SIP domain sip-xmpp.openser.org;
* The "XMPP server" is running on xmpp-sip.openser.org.
In both cases, the destination address must have the same
pattern:
"sip:username<delim>jabber_server@gateway_domain"
From a jabber client's point of view, the destination will look
like:
"sip_username<delim>openser_domain@xmpp_domain"
__________________________________________________________
1.2. Dependencies
1.2.1. OpenSER Modules
The following modules must be loaded before this module:
* requires 'tm' module.
__________________________________________________________
1.2.2. External Libraries or Applications
The following libraries or applications must be installed
before running OpenSER with this module loaded:
* expat - used for parsing/building XML. Linux package:
libexpat1-devel
__________________________________________________________
1.3. Exported Parameters
1.3.1. backend(string)
The mode you are using the module; it can be either "component"
or "server".
Default value is "component".
Example 1-1. Set backend parameter
...
modparam("xmpp", "backend", "server");
...
__________________________________________________________
1.3.2. domain_separator (string)
In the destination address we need an extra character as a
domain separator, apart from @. The address of the XMPP(jabber)
client looks like this:
"sip:username<domain_separator>jabber_server@gateway_domain".
The address of a SIP client has the following pattern :
"sip_username<domain_separator>openser_domain@xmpp_domain"; A
common used character in XMPP transports is "%".
Default value is "*".
Example 1-2. Set domain_separator parameter
...
modparam("xmpp", "domain_separator", "%")
...
__________________________________________________________
1.3.3. gateway_domain (string)
The domain of the gateway, which must resolve in DNS. It must
be the same with the gateway_domain from the destination
address of the XMPP(jabber) client, as seen by the SIP client:
"sip:username<delim>jjabber_server@gateway_domain".
Default value is "sip-xmpp.openser.org".
Example 1-3. Set gateway_domain parameter
...
modparam("xmpp", "gateway_domain", "sip-xmpp.openser.org");
...
__________________________________________________________
1.3.4. xmpp_domain (string)
The XMPP domain of the component or the server, depending on
the mode we are in. It can be the same as the gateway_domain.
For a server DNS name, you need to add _xmpp-server._tcp SRV
records in your DNS zone to enable connections from other XMPP
servers.
Default value is "sip-xmpp.openser.org".
Example 1-4. Set xmpp_domain parameter
...
modparam("xmpp", "xmpp_domain", "xmpp-sip.openser.org");
...
__________________________________________________________
1.3.5. xmpp_host (string)
The IP address or the name of the local XMPP/Jabber server, if
the backend is set to "component". For server mode, this is the
IP address the XMPP component binds to.
Default value is "xmpp.openser.org".
Example 1-5. Set xmpp_host parameter
...
modparam("xmpp", "xmpp_host", "xmpp.openser.org");
...
__________________________________________________________
1.3.6. xmpp_port (integer)
In component mode, this is the port the XMPP server component
interface listens to. In server mode, this is the port the
server listens to.
Default value is "5347", if backend is set to "component" and
"5269", if backend is set to "server".
Example 1-6. Set xmpp_port parameter
...
modparam("xmpp", "xmpp_port", 5269);
...
__________________________________________________________
1.3.7. xmpp_password (string)
The password of the local XMPP server.
This is the password for the component interface on the XMPP
server, when connecting as a component. Default password is
"secret". When connecting to jabberd2, you need to make sure
this is the password configured in the file "c2s.xml". This is
how the default configuration for the jabberd2 looks like:
<router>
...............
<!-- Username/password to authenticate as -->
<user>jabberd</user>; <!-- default: jabberd -->;
<pass>secret</pass>; <!-- default: secret -->;
Example 1-7. Set xmpp_password parameter
...
modparam("xmpp", "xmpp_password", "secret");
...
__________________________________________________________
1.4. Exported Functions
1.4.1. xmpp_send_message()
Converts SIP messages to XMPP(jabber) messages, in order to be
relayed to a XMPP(jabber) client.
Example 1-8. xmpp_send_message() usage
...
xmpp_send_massage();
...
__________________________________________________________
1.5. Configuration
Next is presented a sample configuration file one can use to
implement a standalone SIP-to-XMPP gateway. You can run an
instance of OpenSER on a separate machine or on different port
with the following config, and have the main SIP server
configured to forward all SIP requests for XMPP world to it.
....
#
# $Id: README 5090 2008-10-17 16:49:49Z henningw $
#
# simple quick-start config script for XMPP GW
#
# make sure in your main SIP server that you send
# only the adequate SIP MESSAGES to XMPP GW
#
#
# ----------- global configuration parameters ------------------------
debug=9 # debug level (cmd line: -dddddddddd)
fork=no
log_stderror=yes # (cmd line: -E)
/* Uncomment these lines to enter debugging mode
fork=no
log_stderror=yes
*/
check_via=no # (cmd. line: -v)
dns=no # (cmd. line: -r)
rev_dns=no # (cmd. line: -R)
children=4
listen=udp:10.10.10.10:5076
alias=sip-xmpp.openser.org
# ------------------ module loading ----------------------------------
mpath="/usr/local/openser-1.1.0-xmpp/lib/openser/modules/"
loadmodule "sl.so"
loadmodule "tm.so"
loadmodule "rr.so"
loadmodule "maxfwd.so"
loadmodule "textops.so"
loadmodule "mi_fifo.so"
# XMPP
loadmodule "xmpp.so"
modparam("xmpp", "domain_separator", "*")
modparam("xmpp", "gateway_domain", "sip-xmpp.openser.org")
modparam("xmpp", "xmpp_domain", "xmpp-sip.openser.org")
modparam("xmpp", "xmpp_host", "xmpp.openser.org")
modparam("xmpp", "backend", "server")
# modparam("xmpp", "backend", "component")
# ----------------- setting module-specific parameters ---------------
# -- mi_fifo params --
modparam("mi_fifo", "fifo_name", "/tmp/openser_fifo_xmpp")
# -- usrloc params --
# -- rr params --
# add value to ;lr param to make some broken UAs happy
modparam("rr", "enable_full_lr", 1)
# ------------------------- request routing logic -------------------
# main routing logic
route{
# initial sanity checks -- messages with
# max_forwards==0, or excessively long requests
if (!mf_process_maxfwd_header("10")) {
sl_send_reply("483","Too Many Hops");
exit;
};
if (msg:len >= 2048 ) {
sl_send_reply("513", "Message too big");
exit;
};
### absorb retransmissions ###
if (!t_newtran()) {
sl_reply_error();
return;
}
if (method == "MESSAGE") {
log("*** xmpp-handled MESSAGE message.\n");
if (xmpp_send_message()) {
t_reply("200", "Accepted");
} else {
t_reply("404", "Not found");
}
return;
}
log("*** xmpp: unhandled message type\n");
t_reply("503", "Service unavailable");
return;
}
....
__________________________________________________________
Chapter 2. Developer's Guide
The module does not provide any API to use in other OpenSER
modules.
__________________________________________________________
Chapter 3. Frequently Asked Questions
3.1. Where can I find more about OpenSER?
3.2. Where can I post a question about this module?
3.3. How can I report a bug?
3.1. Where can I find more about OpenSER?
Take a look at http://www.openser.org/.
3.2. Where can I post a question about this module?
First at all check if your question was already answered on one
of our mailing lists:
* User Mailing List -
http://lists.openser.org/cgi-bin/mailman/listinfo/users
* Developer Mailing List -
http://lists.openser.org/cgi-bin/mailman/listinfo/devel
E-mails regarding any stable OpenSER release should be sent to
<users@lists.openser.org> and e-mails regarding development
versions should be sent to <devel@lists.openser.org>.
If you want to keep the mail private, send it to
<team@lists.openser.org>.
3.3. How can I report a bug?
Please follow the guidelines provided at:
http://sourceforge.net/tracker/?group_id=139143.
