
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 modules is a gateway between Openser and a jabber server.
   It enables the exchange of instant messages between SIP
   clients and XMPP(jabber) clients.

   The gateway has two modes to run:

     * the component-mode - the gateway requires a standalone
       XMPP server amd the 'xmpp' module acts as a XMPP component
     * the server-mode - the module acts itself as a XMPP server,
       no requirement for another XMPP server in the system.
       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 relay all your
   connections to a tcp connection to the local jabber server.
   The documentation and the source for a Jabber 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 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 change the jabber server password, which must
       be the same as the xmpp_password parameter.

   A use case, for the component-mode, would look like this:

     * Openser is running on sip-server.openser.org;
     * the gateway is running on sip-xmpp.openser.org;
     * the jabber server is running on xmpp.openser.org;
     * the component is running on xmpp-sip.openser.org.

   In the server mode, the xmpp module is a minimal jabber
   server, thus you do not need to install another jabber server,
   the gateway will connect to the jabber servers, where the
   users you want to chat with have an account.

   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 running on sip-server.openser.org;
     * the gateway is running on 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:

     * libexpat1-devel - used for parsing/building XML.
     _________________________________________________________

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";

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

   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 jabber server, if the
   backend is set to "component"; or the address to bind to in
   the server mode.

   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 the component mode, this is the port of the jabber router
   we connect to. In the server mode, it is the transport address
   to bind 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 jabber server.

   Default value is "secret"; if changed here, it must also be
   changed in the c2s.xml, added by the jabber server. This is
   how the default configuration for the jabberd2 looks like: 
                        <router>
        ...............
        <!-- Username/password to authenticate as --&gt;
    <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 1827 2007-03-12 15:22:53Z bogdan_iancu $
#
# 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://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://openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/devel

   E-mails regarding any stable OpenSER release should be sent to
   <users@openser.org> and e-mails regarding development versions
   should be sent to <devel@openser.org>.

   If you want to keep the mail private, send it to
   <team@openser.org>.

   3.3. How can I report a bug?

   Please follow the guidelines provided at:
   http://sourceforge.net/tracker/?group_id=139143.
