<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Kraken Readme</title>
<style type="text/css">
/* global font and body settings */
body {
font-size : 100%;
background-color : #547B3B;
padding: 0;
margin: 0 0 30px 0;
}
body, td, th {
font-family : arial, helvetica, sans-serif;
font-size : 10pt;
}
pre, tt, code {
font-family : courier new, monospace;
font-size : 9pt;
}
#pageContainer {
display: block;
position: relative;
clear: both;
background-color: #fff;
border: 1px solid #999;
padding: 40px;
margin: 30px;
}
#pageHeader {
display: block;
position: relative;
height: 80px;
background-color: #547B3B;
border: 1px solid #cccccc;
border-bottom: none;
margin: 10px 0 0 0;
}
#pageBody {
margin: 0 18px 0 20px;
}
/* anchors */
a:link {
color: #1B8712;
}
a:visited {
color: #3EAF34;
}
a:hover {
color: #7a1d42;
text-decoration : underline;
}
a:active {
color: #1B8712;
}
/* headings */
h1 {
display: block;
position: relative;
font-size : 1.7em;
font-weight : bold;
color: #ffffff;
padding: 0;
margin: 30px 0 0 20px;
}
h2 {
font-size : 1.3em;
font-weight : bold;
margin: 40px 0 6px 0;
padding: 0;
color: #000000;
}
h3 {
font-size : 1.0em;
font-weight : bold;
margin: 25px 0 3px 0;
padding: 0;
color: #000000;
}
/* general elements */
p {
margin: 0 0 15px 0;
}
ul {
margin: 5px 0 15px 35px;
}
li {
padding-bottom : 4px;
}
tt {
font-family : courier new, monospace;
font-weight : bold;
color : #060;
}
hr {
display: block;
height: 1px;
background-color: #999999;
border: none;
margin: 40px 0 20px 0;
}
.footer {
font-size : 8pt;
color : #666;
text-align : center;
margin-top : 2em;
padding-top : 0.5em;
border-top : 1px #CCC solid;
}
</style>
</head>
<body>
<div id="pageContainer">
<div id="pageHeader">
<h1>Kraken Readme</h1>
</div>
<div id="pageBody">
<h2>Overview</h2>
<p>
The Kraken plugin allows users to log in to and
communicate through other instant messaging services via their XMPP
accounts. The gateway itself provides a number of "transports" to other
protocols (AIM, ICQ, MSN, Yahoo, etc).
</p>
<h2>Terminology</h2>
<p>
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".
</p>
<h2>Installation</h2>
<p>
Copy the kraken.jar into the plugins directory of your Openfire
installation. The plugin will then be automatically deployed. To upgrade to a
new version, copy the new kraken.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.
</p>
<h2>Configuration</h2>
<p>
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 Openfire
Admin Console. You can enable individual transports via the "Settings" sidebar
item, and add new registrations/view existing registrations from the "Registrations"
sidebar item.
</p>
<h2>Using the plugin</h2>
<p>
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 Openfire 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.
</p>
<h3>For admins:</h3>
<p>
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. You will see the full hostnames
of the transports listed. You do <strong>not</strong> have to register these with
your DNS service. They are referenced internally by Openfire and no
external query is necessary.
</p>
<p>
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:
<ul>
<li>AIM: login.oscar.aol.com 5190</li>
<li>GADUGADU: appmsg.gadu-gadu.pl 80</li>
<li>GTALK: talk.google.com 5222</li>
<li>ICQ: login.icq.com 5190</li>
<li>IRC: irc.freenode.net 7000</li>
<li>MSN: messenger.hotmail.com 1863</li>
<li>SIMPLE: localhost 5060</li>
<li>XMPP: jabber.org 5222</li>
<li>Yahoo: scs.msg.yahoo.com 5050</li>
</ul>
Please be aware that these are only the initial connections made. Many of
the services will connect to other servers for difference aspects of your
legacy IM session. All of these connections should stay on the same port
though. There may be ranges of IP addresses or something that you can
open up but I do not know those lists. Also, it is now possible to change
the initial connect host and port via Kraken's
<a href="http://kraken.blathersource.org/node/8">Openfire Properties</a>.
</p>
<p>
There is additional online documentation available at:
<a href="http://kraken.blathersource.org/node/5">Kraken's Online Readme</a>
</p>
<h3>For end users:</h3>
<p>
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)
</p>
<p>
When registering with any Kraken transports, you will see the transport
itself show up in your XMPP roster. This is normal and is how the transport
knows when you are logged in or not, and detects status changes. Removal of
the transport roster items will typically remove your registration with the
transport as well.
</p>
<p>
<strong>Special note for Spark:</strong> As of this release, and an upcoming release
of Spark, you will not have the transports in your roster when you register
from Spark. This is an experimental feature for a smoother user experience.
Note that if you register from Spark and then move to another client, you
will not automatically log into any transports. If you plan to dance between
clients and not use Spark exclusively, I would recommend you register from
another client than Spark.
</p>
<h2>Troubleshooting</h2>
<p>
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.
</p>
<h2>Special Thanks</h2>
<p>
Thanks to the Adium X folk for use of a couple of their service icons!
</p>
<div class="footer">
Copyright © Daniel Henninger, 2008-2010
</div>
</div>
</div>
</body>
</html>