How to configure jabberd2 to work with OpenNMS
- 1 Introduction
- 2 Note on OpenNMS Versions
- 3 Prerequesites
- 4 Create a user for jabberd2
- 5 Build jabberd2 and mu-conference
- 6 Create a few missing directories
- 7 Edit Configuration files
- 8 c2s.xml
- 9 sm.xml
- 10 Start/Stop script
- 11 Start jabberd2
- 12 Creating persistent rooms
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+.
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
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
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
psql -U postgres template1
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".
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:
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
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.
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>
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>
Add an alias for your muc address.
<aliases> <alias name='conference.company.com' target='muclinker'/> </aliases>
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>email@example.com</user> </sadmin> </conference> </jcr>
I found a Jabberd2InitScript somewhere out on the internet. Many thanks to the gentleman who posted it.
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.
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: firstname.lastname@example.org /usr/local/var/jabberd/spool/conference.company.com/ doesn't exist - Create? (Y/N) y Creating Directory Configuring room email@example.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: ]: firstname.lastname@example.org 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): email@example.com JID of owner (Empty line to exit): Admin List: --- JID of admin (Empty line to exit): firstname.lastname@example.org 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.
- 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
- 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 email@example.com
- 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
- First follow:
- Go to Admin -> Configure Users and Groups -> Configure Users -> Add New User
- Give it a username, a password, and for XMPP Address the CHAT_ROOM_NAME@conference.server.ext
- Go to Admin -> Configure Notifications -> Configure Destination Paths -> New Path
- Give it a name, hit Edit, and add the username you just added (or the group if it's in a group)
- 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.