How to configure jabberd2 to work with OpenNMS

From OpenNMS
Jump to: navigation, search

Introduction

Be aware, this is not for the faint-hearted. There are probably easier ways to achieve 80% of the functionality described here. If you want OpenNMS notices sent as instant messages or to a multi-user chat room (very useful) via xmpp (jabber) this is a robust solution. It also allows you to integrate with Microsoft Directory via LDAP....

Note on OpenNMS Versions

These instructions will work with OpenNMS 1.2.4+.

Prerequesites

The XMPPNotification and XMPPGroupNotification strategies have been successfully used with the following.

  • The jabberd2 server, jabberd-2.0s10
  • mu-conference-0.6.0 (using jcr-0.2.4)
  • OpenNMS 1.2.4 (also known to work with the 1.3 line).

Create a user for jabberd2

There's no need to run jabberd2 as root. Create a user (we used jabberd) and optionally group for this service.

Build jabberd2 and mu-conference

Jabberd2

Note that we like to use an LDAP user database for jabberd2 (this enables us to use our Active Directory user database to keep passwords in sync). It does also have a downside in that users cannot update their user database entries via a jabber client.

We also use the same postgres instance as OpenNMS as the back end database for jabberd2. You could use mysql, but as we had a postgres one handy, it seemed to make sense to do it that way. We only disabled mysql. You'll need postgres and postgres-devel packages (but you probably already have these for OpenNMS). You'll also need openldap and openldap-devel if you want to use LDAP.

/configure --enable-ldap --enable-pgsql --disable-mysql make make install

This will put your jabberd2 code in /usr/local/bin and the configuration files in /usr/local/etc/jabberd

create the jabberd2 back end database

cd tools psql -U postgres template1 \i db-setup.pgsql

This will not create a jabber user in the database. You will need to do that (unless you use the default postgres user - not recommended). You will also have to issue the appropriate grants for the resulting database. This document assumes a database user "jabberd2" with password "secret".

mu-conference

The conference (or multi user chat) component is an add-on to jabberd. There isn't one specific to jabberd2, so you have to use the one for jabberd in conjunction with the jabber component runtime (jcr). Untar the jcr, cd into the resulting directory and issue a Make. You'll get a bunch of warnings, but you can (as far as I can tell) safely ignore these.

Copy the mu-conference tarball into the expanded jcr directory and untar it. Then:

cd mu-conference-0.6.0 cp ../src/jcomp.mk ./ cp ../src/main.c ./ make -f jcomp.mk

This should also issue a bunch of warnings but again, you can ignore them. You should have a binary mu-conference created. Copy this to /usr/local/bin/ with the rest of the jabberd2 code. You will also have a configuration file called muc-jcr.xml copy this to /usr/local/etc/jabberd/mu-conference.xml (note the change of name on copy). We will customise this file shortly.

Create a few missing directories

make a few directories that dont get made at installation time:

mkdir -p /usr/local/var/jabberd/log mkdir /usr/local/var/jabberd/db mkdir /usr/local/var/jabberd/pid mkdir /usr/local/var/jabberd/spool chown -R jabberd:jabberd /usr/local/var/jabberd

Edit Configuration files

jabberd2 has a bunch of configuration files that we need to edit:

  • c2s - /usr/local/etc/jabberd/c2s.xml
  • sm - /usr/local/etc/jabberd/sm.xml
  • router - usr/local/etc/jabberd/router.xml
  • mu-conference - /usr/local/etc/jabberd/mu-conference.xml

Note that we make the following assumptions.

The instant messaging service will reside on a server im.company.com. The conference service will reside on the same server, but it's name will be conference.company.com. These should both be resolveable DNS names, but can be aliases to the Canonical name for the host.

All LDAP users live somewhere under the base DN ou=baseou,dn=company,dn=com.

There is a user jabberd with password jabberd under this base DN that we use to bind to the directory.

c2s.xml

This file configures client to server communication, user athentication mechinasims etc. We want to use LDAP, so the relevant sections are:


 .
 .
  <authreg>
    <module>ldap</module>
 .
 .

    <ldap>
      <host>ad.company.com</host>
      <port>389</port>
                                                                                                                             
                                                                                                                            
                                                                                                                            
     <binddn>CN=jabberd,OU=baseou,DC=company,DC=com</binddn>
     <bindpw>jabberd</bindpw>
                                                                                                                            
     <uidattr>sAMAccountName</uidattr>
                                                                                                                            
         <basedn>ou=baseou,dc=company,dc=com</basedn>
   </ldap>

</nowiki> </code>

sm.xml

Session manager configuration - This has to be customised for your IM server id and to use the postgres back end database

.
<id>im.company.com</id>
.
.
 <storage>
    <driver>pgsql</driver>
    <pgsql>
      <host>localhost</host>
      <port>5432</port>
                                                                                                                            
      <dbname>jabberd2</dbname>
                                                                                                                            
      <user>jabberd2</user>
      <pass>secret</pass>
                                                                                                                            
      <transactions/>
    </pgsql>
</storage>

Router.xml

Add an alias for your muc address.

 <aliases>
   <alias name='conference.company.com' target='muclinker'/>
 </aliases>

mu-conference.xml

I have included my configuration in its entirety here:


<jcr>
  <name>muclinker</name>
  <host>conference.company.com</host>
  <ip>im.company.com</ip>
  <port>5347</port>
  <secret>secret</secret>

  <spool>/usr/local/var/jabberd/spool/conference.company.com</spool>
  <logdir>/usr/local/var/jabberd/log</logdir>
  <pidfile>/usr/local/var/jabberd/pid/mu-conference.pid</pidfile>
  <loglevel>256</loglevel>
    <conference xmlns="jabber:config:conference">
      <public/>
      <vCard>
        <FN>OpenNMS Chatrooms</FN>
        <DESC>This service is for public chatrooms.</DESC>
        <URL>http://opennms.company.com:8080/opennms/</URL>
      </vCard>
      <history>200</history>
      <logdir>/usr/local/var/jabberd/log</logdir>
     <notice>
        <join>has become available</join>
        <leave>has left</leave>
        <rename>is now known as</rename>
      </notice>
      <sadmin>
        <user>opennms@im.company.com</user>
      </sadmin>
    </conference>
 </jcr>

Start/Stop script

I found a Jabberd2InitScript somewhere out on the internet. Many thanks to the gentleman who posted it.

Start jabberd2

You can start/stop jabberd2 using the Jabberd2InitScript. You probably want to have it start in run state 2 or 3. The config that we have created will log everything to syslog.

Thats all there is to it ;-).

Creating persistent rooms

By default, the multi user chat part of the jabberd2 installation will dynamically create a room when the first user attempts to join a room. There may be circumstances under which we would like finer grained control over the room's behaviour. We may also want the room to be persistent. By default dynamic rooms will be removed shortly after the last person leaves. We may not want that. Luckily, mu-conference ships with a couple of scripts that can be used to pre-configure rooms (roommaker.pl and roomname.pl). Alternatively, some clients may support the right commands to create persistent rooms remotely.

roommaker.pl

Here's how I managed to create a room using roommaker.pl

With the jabberd2 service stopped.....


# ./roommaker.pl
Please enter spool directory path (e.g. /usr/local/jabber/spool): /usr/local/var/jabberd/spool
Please enter jid for the room: opennms@conference.company.com
/usr/local/var/jabberd/spool/conference.company.com/ doesn't exist - Create? (Y/N) y
Creating Directory

Configuring room opennms@conference.company.com
Filename: /usr/local/var/jabberd/spool/conference.company.com/75c014a6106edd06586361792f36e079f042d88d.xml

General Options
---
Room name (text) [Default: opennms]:
Password (text) [Default: ]:
Room description/MOTD (text) [Default: ]: the room for opennms alerts
Room subject (text) [Default: ]: todays notices
Bare JID of room creator (text) [Default: ]: jonathan@im.company.com
Is room public (0/1) [Default: 0]: 1
Maximum Users  (value) [Default: 0]: 64

Permission Options
---
Allow non-admins to see real jids (0/1) [Default: 0]:
Can users change subject (0/1) [Default: 0]: 1
Allow users to IQ query other users (0/1) [Default: 0]: 1

Legacy Options:
---
Consider all clients legacy (0/1) [Default: 0]:
Legacy join message (text) [Default: ]:

Legacy leave message (text) [Default: ]:
Legacy rename message (text) [Default: ]:

Moderation Options:
---
Is room moderated (0/1) [Default: 0]:
Skipping Moderation options

Member-Only Options:
---
Make room member-only (0/1) [Default: 0]:
Skipping Moderation options

Logging Options:
---
Enable native room logging (0/1) [Default: 0]: 1
Log Format
0] Plain Text
1] XML
2] XHTML
 [Default: 0]: 0

Owner List:
---
JID of owner (Empty line to exit): jonathan@im.company.com
JID of owner (Empty line to exit):

Admin List:
---
JID of admin (Empty line to exit): jonathan@im.company.com
JID of admin (Empty line to exit):

Member List:
---
JID of member (Empty line to exit):

Outcast List:
---
JID of outcast (Empty line to exit):

Writing Room definition file
Room registry not found. Creating

Writing updated Room registry file
[jabberd@opennms scripts]


Adding xmppMessage abilities to OpenNMS

A: You'll need an jabber (XMPP) server, jabberd2 for example, works well. Youll need an account on this server for the OpenNMS daemon and all the users who you want to send xmpp notifications.

  1. Edit $OPENNMS_HOME/etc/xmpp-configuration.properties and add lines like these:
xmpp.server = xmpp.yourdomain.com
xmpp.user   = opennms-user
xmpp.pass   = opennms-password
  1. Add XMPP addresses for your users in users.xml (or via the WebUI - Home > Admin > Users and Groups > User List > Modify User). These addresses are of the format username@xmpp.yourdomain.com
  2. Create a destination path for XMPP notifications that uses the xmppMessage notification command, and configure your notices to use that destination path.


Adding xmppGroupMessage abilities to OpenNMS

  1. First follow:
    1. Jabberd2 and OpenNMS docs: http://www.opennms.org/index.php/How_to_configure_jabberd2_to_work_with_OpenNMS
    2. and Bottom of: http://www.opennms.org/index.php/FAQ-Configuration#Q:_How_can_I_use_jabber_.28XMPP.29_notifications.3F
  2. Go to Admin -> Configure Users and Groups -> Configure Users -> Add New User
    1. Give it a username, a password, and for XMPP Address the CHAT_ROOM_NAME@conference.server.ext
  3. Go to Admin -> Configure Notifications -> Configure Destination Paths -> New Path
    1. Give it a name, hit Edit, and add the username you just added (or the group if it's in a group)
  4. Go to Admin -> Configure Notifications -> Configure Event Notifications -> ... at the last step you can

choose a path, select the one you created!

Note on setting XMPP Group Message with Openfire Server

I couldn't get this method to work with a Room created in Openfire until I removed the password from the Room Settings of the created room. Though not sure if necessary, I subsequently removed it from the OpenmNMS xmppGroup user created with the conference room xmpp id.