How to run Spectrum 2 withOpenfire - Gojara plugin Guide
"Spectrum 2 is an XMPP transport/gateway and also simple server. It allows XMPP users to communicate with their friends who are using one of the supported networks."
We use Spectrum 2 as an external component to extend Openfire, making it possible to connect to different protocols within your Instant Messenger.
To make Spectrum 2 work nicely with Openfire, we developed the OF-plugin Gojara.
This document will guide you through the following steps:
- Installing Spectrum 2 & configuring Spectrum 2 + Openfire
- Installing Gojara & configuring Gojara
- migrating user-credentials from kraken to spectrum 2
I will try my best to give you the information you need to work with Spectrum2. If you have any suggestions for improving this document, feel free to write a pm / email.
Before we start, let's talk about some important things Spectrum2 / Gojara can and CANNOT do so you don't set this up to later find out it's not what you wanted.
- Spectrum 2 does currently (July 2013) NOT SUPPORT FILETRANSFER. For further Questions please contact the Spectrum 2 developers at www.spectrum.im
- Although Spectrum 2 supports protocols like Skype / Facebook, these are currently ( July 2013 ) not tested with Gojara / OF and getting these to work was not the purpose of this plugin. This may change in the future, but for our purposes libpurple is sufficient.
- Adding contacts works, but may be a bit bothersome at times. Best practice is to add contacts from your native client and then everything works fine.
- How to run Spectrum 2 withOpenfire - Gojara plugin Guide
- Spectrum 2
We only use Spectrum 2 on linux machines, so this guide will not cover anything Windows related.
You can install Spectrum 2 from repositories:
- For Debian/Ubuntu: http://spectrum.im/documentation/installation/debian_ubuntu.html
- For Fedora/RHEL/CentOS: http://spectrum.im/documentation/installation/fedora_rhel.html
- You could also install it from source, though i wouldn't recommend it unless you want to run some kind of patched version of S2. Please refer to http://spectrum.im/documentation/ Installation section for this.
Spectrum 2 backends are external components which need to connect to the OF-Server. Of course you need to enable External Components for this to work.
- In your Openfire admin console goto: Server -> Server Settings -> External Components.
- Set Service Enabled to Enabled. Standard Port is 5275, you can set a different password.
- If you don't want to set "Allowed to Connect" to Anyone, you need to whitelist the component. The name of the component will be something like "icq.your-domain", see Spectrum 2 configuration.
Configuring Spectrum 2
Most of this is already covered in http://spectrum.im/documentation/tutorials/gateway_mode.html , but I'll provide a quick overview.
Spectrum 2 config files are located at /etc/spectrum2/.
Transport config files are at /etc/spectrum2/transports/.
There is a default spectrum.cfg.example provided which you should copy, rename and edit. You need a .cfg file for EACH protocol you want to enable.
Most settings in there are already documented well, but let's look at our most important ones. This should work for all protocols supported by libpurple.
- server_mode ---> This should be 0. This means Gateway mode, as we don't need server functionality (we have OF for that).
- jid ---> Jabber-ID for the transport (or Openfire-component). E.g. "icq.yourdomain.tld". Please be aware that your server name may not be the same as your host Name / XMPP domain. Look this up in Server -> Server Manager -> Server Information or System Properties -> xmpp.domain.
You really should stick to this naming convention, as OF can only correctly show the icq image if the subdomain starts with icq., same for msn etc.
- admin_jid ---> This field needs to be added somewhere in the service area. It's the JID of the Account that will be able to send/receive spectrum2_manager commands via xmpp, should be gojaraadmin@yourdomain.
If you don't set this to gojaraadmin@yourdomain, gojara will not correctly show gateway session/registration details and unregister from console won't work.
- password ---> Password for connecting the component to Openfire, you configured this earlier.
- server ---> Where is your XMPP Server running? (respectively "domain.tld"). S2 needs to be able to resolve this.
- port ---> Port the Gateway should use to connect to OF. We set the default to 5275 earlier.
- backend_host ---> localhost, when Spectrum2 is running on the same machine as the backends.
- backend ---> Path to the backend you want to use for this Transport. For example: "backend=/usr/bin/spectrum2_libpurple_backend".
- protocol ---> Libpurple Protocol ID, see List of Protocol Identifiers for further info. https://wiki.instantbird.org/Protocol_Identifiers
[database] ---> For simple sqlite3 usage this doesn't really need to be edited. We use postgres so I'll still explain this configuration.
- type ---> For postgres this needs to be set to "pqxx".
- database ---> Name of the Database we want to use.
- server ---> Server the DB is running on, localhost if same server.
- port ---> Port that should be used for connecting.
- user ---> Name of the User/Role we want to use.
- password ---> If configured for md5, we need to set the password for the role configured above. Of course there are also other authentication methods you can configure.
- prefix ---> Value the tables used for specific transport will be prefixed with. Probably should be set or it will insert users of different transports into the same table. Does not need to be set for sqlite usage, as in that case, S2 creates a separate DB for each transport in /var/lib/spectrum2/
- connectionstring --> Does not need to be set as we configured the values above.
Configuring for Debugging:
To be able to debug incoming or outgoing XMPP Messages correctly, we should enable XML Logging for Spectrum2. With this ON, S2 will write the content of XMPP Packages to its logfiles. We then can easily grep these logs to find errors / figure out the workflow. Of course, this should not be set to ON on production.
/etc/spectrum2/logging.cfg ---> log4j.category.Component.XML = ON|OFF
These settings will be overwritten on a new install of Spectrum2 ( unlike gateway cfgs located in /etc/spectrum2/transports/ ) but probably not by upgrade.
List of important directories:
/etc/spectrum2/ --> This is where the configuration files are located.When S2 is started, it looks here for cfgs and will try to create an instance accordingly.
/var/log/spectrum2/ --> This is where the logfiles for each configured instance are located. It contains the Spectrum2.log, as well as the Backend.log. Spectrum2.log contains logs to most actions handled by Spectrum2, while the backend.log contains Information about the specific backend Spectrum2 uses to do its work (connect to loginservers, etc.).
/var/lib/spectrum2/ --> This directory contains the databases created when used with SQLite3, as well as coredumps related to specific transports.
/var/run/spectrum2/ --> Contains the PIDs related to started Spectrum2 Instances.
You can interact with Spectrum2 via spectrum2_manager. All available commands are listed here: http://spectrum.im/documentation/management/spectrum2_manager.html
For a simple start, type "spectrum2_manager start" in the shell. It starts a transport for each configurationfile in /etc/spectrum2/transports/ that ENDS on .cfg (so the example one will be skipped).
You can directly adress a specific transport by supplying its JID to spectrum2_manager , e.g: "spectrum2_manager icq.your-domain stop"
See this thread:
Installing Gojara is simple, just open the openfire console and in the Plugins section select Gojara.jar and upload it. You can delete it by clicking on the red X.
Gojara now extends the openfire console with some new pages, here is a quick overview:
- Server -> Server Settings -> GoJara ---> Used for configuring Gojara and viewing Statistics as well as live logging
- Server -> Server Manager -> Spectrum2 Stats ---> If admin_jid & spectrum2 is correctly configured, will show some statistics like Uptime, Memory Usage and messages sent / received for each transport.
- Sessions -> Active Sessions -> Gateway Sessions ---> Overview of OF-Users currently connected to a gateway via Spectrum 2
- Sessions -> Tools -> Gateway Registration Overview ---> Overview of all Users that at some point entered login credentials or actually connected to a gateway via Spectrum 2. If admin_jid & spectrum2 is correctly configured, you will be able to manually unregister registrations from the OF-Console
- Session Details ---> Will show active Sessions and existing Registrations for selected user. Click on a session entry / registration entry in respective overviews to see this view.
We are not quite done yet. Without configuration, Spectrum 2 will send a authorization request for EVERY transport on your gateway contact list. There are also some additional features you might want to use that can be configured for Gojara.
Go to Server-> Server Settings -> Gojara.
You should check each connected gateway to enable remote roster. Clicking on the symbols in the component bar will expand the bar and display some additional information. Clicking on the Groups icon will let you limit access to this gateway to specific Openfire-groups. This will be explained in more detail in a later section
- General Options:
- Persistent Roster
When persistent Roster is enabled, ALL CONTACTS that are "imported" into OF through the gateway will NOT be deleted when you log out again. This makes your roster bloat up quite a bit if you use a lot of transports. Unless you really need / want this somehow, we recommmend NOT enabling persistent Roster.
- Only allow internal Jabber Conferences
Spectrum 2 might show MUC (Multi User Chat) as a supported feature of some Transports. If this should not be allowed because you only want to use internal Jabber Conferences, check this to make Gojara remove these.
- Do not add Subdomains to Roster
Some clients show the Subdomain as a Contact on the Roster (Spark does, Gajim doesn't). If you have a client behaving like Spark and you dont want this, enable this. Gajim users should NOT enable it.
- Client specific Features:
If you use spark, enable these. For other clients, these shouldn't harm your experience, but you might want to try toggling thes if you experience issues. We work with spark exclusively though, so we didn't really test other clients (except Gajim).
- Block presence pushing to rosterItems except gateway
Spark specific option so you can let Spark decide if you want to automatically connect to gateway on startup or not.
Ok! Basic configuration is done! If you set up Spectrum 2 correctly and started it, the gateways should now should show up when you log into your Messenger.
Configuring Access Control
- If you did not already do it, create a Group at Users/Groups -> Groups -> Create new Group, for example ICQWhiteList.
- normally you dont want groupmembers to see other groupmembers, so disable contact-list group-sharing.
- At Server -> Server Settings -> GoJara add the Group to the corresponding transport-whitelist & save settings.
Adding a User
Best do this from a native client, but most of the times it works fine.
Unregistering a registration
If you correctly configured Spectrum 2 to include the admin_jid = gojaraadmin@yourdomain then you will be able to unregister a user from Spectrum 2. This means that if the user is currently online, he will be forced offline and will have to REENTER his login credentials.
If a user entered his login-credentials with a wrong password and does not know how to reset his credentials within his messenger, you can still unregister him from Spectrum 2 via the registration Overview. He will then be prompted to enter his credentials again.
Unregistering a user from Spectrum 2 will clear all data Spectrum 2 saved regarding this user.
Session / Registration Overview + Spectrum 2 Stats
Migrating user-credentials from Kraken to Spectrum 2
Holger developed a plugin to migrate existing user-credentials from Kraken to Spectrum 2. You can find the Plugin as well as a detailed description of the necessary steps here:
Be sure to use the latest version, currently the one attached to this post:
Unable to register with transport
Every time we hit this error it was due to spectrum2 jid not being correctly configured. Please check if jid in your spectrum .cfg files is configured according to the guidelines i mentioned in configuring Spectrum2. If this is the case and it still does not work, please pm / email me or write something in the gojara community thread.
Spectrum2 related problems
As we have quite many components working together to achieve this functionality, it may sometimes be difficult to determine which part is actually failing. I already explained how you can contact the spectrum 2 developers, but there are some special cases that we can resolve here.
Gtalk does not work with Google Apps account, only standard Gmail Acc
(thanks Tomas Hruska)
Ok, solved. Add this to Gtalk cfg file:
And voila you can login with your Gapps domain account.
ICQ Connection Problems
ICQ has changed its server and protocol. Some really old versions of libpurple in some cases fail to login. If (and only if) the default configuration does not work for you, you should add these settings to your config file:
[purple] server=login.icq.com use_clientlogin=1 encryption=no_encryption
This will disallow encryption from Spectrum to ICQ server, but there is currently no other way how to make it work.
Regarding different clients
Although we have been investing quite some time now, Gojara is still pretty "young" and not really tested in some scenarios. There is also the fact that many clients vary widely considering actual implementation. This means: Gojara is mainly developed for Spark, as this is the main use-case for us. We will still try to get other clients working though, provided it can be done in reasonable time.
As there are differences in the handling of gateways in Gajim / Spark, you need to tune some settings to make Gajim work properly with Gojara.
If you want to use features like not adding the subdomain to your roster, you need to enable the gojara setting for Gajim presence pushing. If you don't have any of these requirements however, you should minimally configure Gojara like this:
Do not add Subdomains to roster - UNCHECKED
Presence pushing to rosterItems except gateway - UNCHECKED
If you still experience Issues with autoconnecting, try reloading Gojara and/or setting
Enable persistent Roster - CHECKED
If there is anything you want me to add to this Guide or you have a problem, please create a thread in the Gojara community plugin space!