ADD_TEXTILE("about.textile" "Spectrum 2 - What is Spectrum 2?")

ADD_TEXTILE("configure_xmpp_server.textile" "Spectrum 2 - Configure XMPP server")

ADD_TEXTILE("tutorial_gateway_mode.textile" "Spectrum 2 - Spectrum 2 in gateway mode")

Spectrum 2 is an XMPP transport/gateway and XMPP server. It allows XMPP users to communicate with their friends who are using one of the supported networks. It supports a wide range of different networks such as ICQ, XMPP (Jabber, GTalk), AIM, MSN, Facebook, Twitter, Gadu-Gadu, IRC and SIMPLE. Spectrum is written in C++ and uses the Swiften XMPP library and different libraries for legacy networks. Spectrum 2 is open source and released under the GNU GPL2+ license.

h2. Gateway mode and server mode

Spectrum 2 can work in two modes: Gateway mode and Server mode. This chapter describes differences betweeen those two modes. If you want to find out how to configure Spectrum 2 to run in gateway or server mode, read the Configuration part of this documentation.

h3. Gateway mode

Gateway mode represents the classic way how XMPP gateway works. You have to configure an external XMPP server (like Prosody or Ejabberd) to serve the subdomain you want to use for Spectrum 2 (for example "icq.domain.tld"). Spectrum 2 in gateway mode then connects the XMPP server as its component and users are able to find out "icq.domain.tld" in Service Discovery, register it and use it.

*Advantages:*

* Users can use more legacy networks using single XMPP account (and using single TCP connection).

* It's easy to extend existing XMPP servers using gateway mode.

*Disadvantages:*

* Passwords are stored (even in encrypted form) on server.

* Roster (contact list) synchronization can be problematic, because it depends on the client user uses. This can be improved by usage of Remote Roster protoXEP.

* You have to setup XMPP server and use database even if you only want to use Spectrum 2 as a tool to connect legacy networks using XMPP protocol.

h3. Server mode

In server mode, Spectrum 2 behaves as standalone server. User then logins legacy networks by logging XMPP account like this one: "my_msn_name%hotmail.com@msn.domain.tld".

*Advantages:*

* Passwords are not stored on server.

* Roster synchronization is easy, because Spectrum 2 acts as normal server.

* If you want to use Spectrum 2 as wrapper between different networks, you don't need database or Jabber server as another layer.

* Using SRV records you can easily run Spectrum 2 on different machines to scale it.

*Disadvantages:*

* Clients have to support more accounts to connect more legacy networks (Therefore they will need have to use more TCP connections).

h2. Spectrum 2 instance, Spectrum 2 main process and backends

This chapter describes differences between Spectrum 2 instance, Spectrum 2 main process and Spectrum 2 backends.

h3. Spectrum 2 instance

In server mode, Spectrum 2 instance is single XMPP server. In gateway mode, it is single XMPP gateway. We can say these statements about Spectrum 2 instance:

* One instance is defined by one configuration file (By default stored in /etc/spectrum2/transports/).

* Spectrum 2 instance is represented to end user by its Jabber ID (for example icq.domain.tld).

* Internally every Spectrum 2 instance consists of Spectrum 2 main process and Spectrum 2 backends.

* One instance can run just one type of Spectrum 2 backend.

h3. Spectrum 2 main process

Spectrum 2 main process is the main process of Spectrum 2 instance.

* Spectrum 2 main process is responsible for running Spectrum 2 backends and routing users' requests to proper backend.

* By default the logs of Spectrum 2 main process are stored in /var/log/spectrum2/<jid>/spectrum2.log.

h3. Spectrum 2 backend

Spectrum 2 backend is special application run by Spectrum 2 main process. The goal of Spectrum 2 backend is to handle users's sessions. Spectrum 2 main process can handle more Spectrum 2 backends, but all messages from single user are always handled by the same backend.

One Spectrum 2 instance can run only one type of Spectrum 2 backend.

To use Spectrum 2 in gateway mode, you have to configure your XMPP server to work with your Spectrum 2 instances.

The configuration details you give to your XMPP server of course have to correspond to the details you give in the Spectrum 2 configuration file.

h2. DNS records configuration

For every Spectrum 2 instance you have to create a nameserver record for the transport's Jabber ID, if you want users of other servers to connect to your transport. A SRV record for "server to server" connections like in the following example is preferred:

<pre>

_xmpp-server._tcp.j2j.example.com. IN SRV 0 5 5269 jabber.example.com.

</pre>

Otherwise you could set an A level record for the JID of your instances.

See also: "http://prosody.im/doc/dns":http://prosody.im/doc/dns

h2. Ejabberd

In the Ejabberd configuration file (by default in /etc/ejabberd/ejabberd.cfg), you have to add a field to the "listen" directive. 

In the section that says: ‘{listen,’ add these lines:

<pre>

{{5347, "127.0.0.1"}, ejabberd_service, [

                                        {access, all},

                                        {host, "icq.example.com", [{password, "secret"}]}

]}

</pre>

* @5347@ is port on which Ejabberd will listen for Spectrum 2 so Spectrum 2 can connect this port and start serving the hostname you've configured. Each Spectrum 2 instance has to be connected to different port.

* "@icq.example.com@" is the hostname of your Spectrum 2 transport.

* "@secret@" is the password which will be used by Spectrum 2 to authenticate itself to the Ejabberd server.

* "@{access, all}@" lets everybody use your transport. 

To use the new settings, you can either just restart Ejabberd or use Ejabberd's web-interface to add the new port to the running instance. You can find the Settings under Nodes -> <your node> -> Listened Ports. For full information on how to add external components (like Spectrum 2) to your Ejabberd installation, also refer to the "Ejabberd guide":http://www.process-one.net/en/ejabberd/guide_en.

h2. Prosody

In the prosody configuration file (normally in /etc/prosody/prosody.cfg.lua) there is configuration line for components.

It looks like this:

<pre>

--Component "gateway.example.com"

--      component_secret = "password"

</pre>

You have to edit this line to make Spectrum 2 work:

Example: ICQ

<pre>

Component "icq.example.com"

     component_secret = "mysecreticqpassword"

</pre>

For every spectrum transport you want to use, you have to add those two lines:

Example:

<pre>

Component "icq.example.com"

     component_secret = "mysecreticqpassword"

Component "msn.example.com"

     component_secret = "mysecretmsnpassword"

Component "yahoo.example.com"

     component_secret = "mysecretyahoopassword"

</pre>

Save the file and restart your Prosody server.

* "What is Spectrum 2?":about.html

h2. Tutorials

* "Spectrum 2 in gateway mode":tutorial_gateway_mode.html

h2. Before you start

* Check that you really want to run Spectrum 2 in gateway mode and not in server mode. The difference is documentation on "What is Spectrum 2?":about.html page.

* Install Spectrum 2.  Installation is covered in "Installation section on the main page":index.html.

h2. Configure your XMPP server

XMPP server configuration is addressed on "Configure XMPP server page":configure_xmpp_server.html.

h2. Configure Spectrum 2

Default config file is located at @/etc/spectrum2/transports/spectrum.cfg.example@. To successfully connect Spectrum 2 to your server, change the following options in the following categories and remove the .example suffix (you can name the file as you want, but it has to have .cfg suffix):

|_. Category|_. Option|_. Change to value|_. Meaning|

|service|server_mode|0| Spectrum 2 will act as gateway.|

|service|jid|Jabber ID of your Spectrum 2 transport|You have configured the Jabber ID in your Jabber server config file in previous step.|

|service|password|Password to connect the Jabber server|You have configured the password in your Jabber server config file in previous step.|

|service|server|Your Jabber server IP od hostname|Spectrum 2 will connect that IP/hostname.|

|service|port|Jabber server port to which Spectrum 2 connects|You have configured the port in your Jabber server config file in previous step.|

All config options with description are located at "Config file page":config_file.html.

h3. Choose the Spectrum 2 backend and legacy network

You have to choose the Spectrum 2 backend and legacy network to which this Spectrum 2 gateway will connect the users.

The default backend is "Libpurple backend":libpurple.html. Read the "Libpurple backend documentation":libpurple.html to see how to choose particular legacy network. If you want to use different backend, change the path to it according to "List of backends":backends.html.

h3. Choose the storage backend

|_. Category|_. Option|_. Change to value|_. Meaning|

|database|type|sqlite3|Spectrum 2 will use SQLite3 as storage backend|

h2. Start Spectrum 2

The following command should now start your first Spectrum 2 instance:

<pre>

spectrum2_manager start

</pre>

h2. If something goes wrong

Spectrum 2 logs important messages into @/var/log/spectrum2/<jabber_id>/spectrum2.log@. It's always good to check that log if something goes wrong.