# IM Gateway Readme

## Overview

The IM (instant messaging) gateway plugin allows users to log in to and communicate through other instant messaging services via their Jabber accounts. The gateway itself provides a number of "transports" to other protocols (AIM, ICQ, MSN, Yahoo, etc).

## Terminology

To help identify the differences between the plugin as a whole and the underlying interfaces to external protocols (AIM, ICQ, etc), we refer to the plugin itself as the "gateway" while we refer to the protocol handlers as "transports".

## Installation

Copy the gateway.jar into the plugins directory of your Wildfire installation. The plugin will then be automatically deployed. To upgrade to a new version, copy the new gateway.jar file over the existing file. Please be aware that an upgrade will cause all of the users on your server who are making use of the plugin to be disconnected from their external IM accounts. Your users should be reconnected after the plugin reloads.

## Configuration

By default, after the plugin has been deployed all of its features are disabled. This plugin is configured via the "Gateways" sidebar item located in the Wildfire Admin Console. You can enable individual transports via the "Settings" sidebar item, and add new registrations/view existing registrations from the "Registrations" sidebar item.

## Using the plugin

Before going into specifics, there are some important things you need to know first. A user must be registered with a transport in order to make use of it. Registration is the process wherein a user tells a transport what username and password will be used with the external service. This process also places the transport JID in their roster to that the transport itself can "hear" them come online, and act appropriately (logging them in and such). In this case, we interact with the user's roster directly, so there is no need for a flood of subscription requests to the client itself. A side effect of this is that only users of the local Wildfire server will be able to make use of any transport on the gateway. Roster items are created as non-persistent, which means that when the end user logs out or disconnects from the gateway, the associated transport roster items will no longer exist in their roster.

### For admins:

The web interface of the gateway plugin provides a mechanism for setting up registrations on a user's behalf, as well as editing and deleting them. It also provides tools for monitoring who is using the gateway, their status, etc. In a typical setup, a user will be allowed to register an account themselves. See the next section for details on this. You can also set who has access to the specific transports and even enforce manual registrations only. If a specific transport has any options, they will be made available from the web interface.

If you have a firewall set up, you do not need to open any inbound ports. However, you will need to make sure the following outgoing connections will work based on the transport in question:

- AIM: login.oscar.aol.com 5190
- ICQ: login.oscar.aol.com 5190
- IRC: currently irc.freenode.net 7000 (in the future this will be configurable)
- MSN: messenger.hotmail.com 1863
- Yahoo: scs.msg.yahoo.com 5050

There is additional documentation available at: IM Gateway Plugin Wiki

### For end users:

Typically, users will use Service Discovery (aka disco) to find out what services are available on a server, and then will be provided with a way to register with whatever transports are made available. Some clients do not have the functionality to interact with transports. In this case, a server admin will need to register the user on their behalf. (see above)

## Trouble shooting

If the plugin behaviour is not as expected you can enable server debug logging. This will allow the plugin to start logging. Server debug logging should only be enabled temporarily, as it will generate a lot of additional logging that will both slow your server down and consume a lot of disk space.