---

layout: page

title: Spectrum 2

---

Spectrum 2 introduces backends. Backends are external application which provides a way how to connect to legacy networks, so it's possible to use even different libraries than Libpurple to connect the legacy network. However, Libpurple is still the best library to use so far.

This page contains the list of currently supported backends with the basic information about them.

### How to change backend

Backends are switched in Spectrum 2 config file using the following option:

Section| Option| Value

-------|-------|------

service|backend|Full path to the backend binary

### List of backends

Name| Supported networks| Default path to backend

----|-------------------|-------------------------

Libpurple backend|AIM, Jabber, Facebook, GTalk, ICQ, MSN, Yahoo|`/usr/bin/spectrum2_libpurple_backend`

Swiften backend|Jabber, Facebook, GTalk|`/usr/bin/spectrum2_swiften_backend`

SLibCommuni backend|IRC|`/usr/bin/spectrum2_libcommuni_backend`

Frotz backend|Allows playing interactive-fiction games|`/usr/bin/spectrum2_frotz_backend`

Skype backend|Skype using the official client|`/usr/bin/spectrum2_skype_backend`

SMSTools3 backend|SMS using connected mobile phone|`/usr/bin/spectrum2_smstools3_backend`

Twitter backend|Twitter|`/usr/bin/spectrum2_twitter_backend`

---

layout: page

title: Spectrum 2

---

## Description

LibCommuni backend is IRC backend which uses [Communi IRC library](https://github.com/communi/communi/wiki). It's specialized IRC backend and it should replace libpurple IRC support.

### Configuration

You have to choose this backend in Spectrum 2 configuration file to use it:

	[service]

	backend=/usr/bin/spectrum2_libcommuni_backend

LibCommuni backend can then work in two modes.

### One transport per one IRC network

This is preferred way if you know that you or your users will need to connect just one IRC network. It's also good mode of you maintain IRC server and want to provide XMPP access to it.

In this mode users can:

* connect the IRC network without joining the IRC channel.

* identify to NickServ (or any other service like that) using username and password from transport registration.

* have IRC contacts in their rosters. (Not done yet, but it's planned)

* see channel list in the service discovery. (Not done yet, but it's planned)

To use this mode, you have to configure irc_server variable like this:

	[service]

	irc_server=irc.freenode.org

### One transport for more IRC networks

In this mode users can connect more IRC networks, but they can't connect the network without being in the room. To connect the network, user has to join the room in following format: #room%irc.freenode.org@irc.domain.tld. The nickname used in the first join request is used as a nickname for the IRC connection.

###  All configuration variables

Key | Type | Default | Description

----|------|---------|------------

irc_server | string | | IRC server hostname for "One transport per one IRC network" mode.

irc_identify | string | NickServ identify $name $password | The fiirst word is nickname of service used for identifying. After the nickname there's a message sent to that service. $name is replaced by the username defined by user in the registration. $password is replaced by password.

---

layout: page

title: Spectrum 2

---

### Description

Libpurple backend is backend based on Librpurple library supporting all the networks supported by libpurple

### Configuration

You have to choose this backend in Spectrum 2 configuration file to use it:

	[service]

	backend=/usr/bin/spectrum2_libpurple_backend

There is also special configuration variable in "service" called @protocol@ which decides which Libpurple's protocol will be used:

Protocol variable| Description

-----------------|------------

prpl-jabber| Jabber/Facebook/GTalk

prpl-aim|AIM

prpl-icq|ICQ

prpl-msn|MSN

prpl-yahoo|Yahoo

prpl-gg|Gadu Gadu

prpl-novell|Groupwise

---

layout: page

title: Spectrum 2

---

### Description

Skype is supported by Spectrum 2, but in quite specific way. It's not possible to connect the Skype network without official Skype client running. Therefore you have to have official Skype client installed. Official Skype client is then run for every connected user and Spectrum 2 communicate with it using the DBus interface. One Skype client instance needs approximately 50MB of RAM, therefore Skype transport needs lot of memory (50MB per user).

### Configuration

You have to have:

* Official Skype client installed in Linux PATH

* DBus installed and have running DBus daemon

* xvfb-run tool installed

If you have those depencencies ready, you just have to set the proper backend configuration variable:

	[service]

	backend=/usr/bin/xvfb-run -n BACKEND_ID -s "-screen 0 10x10x8" -f /tmp/x-skype-gw /usr/bin/spectrum2_skype_backend

---

layout: page

title: Spectrum 2

---

### Description

Swiften backend is backend based on Swiften XMPP library. This backend can be used to connect XMPP based networks like Jabber, Facebook or GTalk. In comparison with Libpurple backend, it doesn't need so much memory and CPU time and therefore scales better for XMPP networks.

### Configuration

You have to choose this backend in Spectrum 2 configuration file to use it:

	[service]

	backend=/usr/bin/spectrum2_swiften_backend

---

layout: page

title: Spectrum 2

---

### Description

Twitter backend is backend created during Summer of Code. It allows users to connect Twitter network.

### Configuration

You have to choose this backend in Spectrum 2 configuration file to use it:

	[service]

	backend=/usr/bin/spectrum2_twitter_backend

---

layout: page

title: Spectrum 2

---

### Compatibility with Spectrum 1

Spectrum 2 config file is not compatible with Spectrum 1, although some important config options are named the same as in Spectrum 1.

### [service] section

#### General settings

Key | Type | Default | Description

----|------|---------|------------

server_mode | boolean | 0 | True if Spectrum should run as server in [server-mode](http://spectrum.im/projects/spectrum/wiki/Spectrum_2_Admin_-_New_design#Server-mode).

jid | string | | Jabber ID of Spectrum2 instance. For example "localhost", "icq.domain.tld".

server | string | | Hostname or IP address of server to which Spectrum connects in gateway-mode.

port | integer | 0 | Port on which Spectrum listens to in server-mode or to which connects in gateway-mode.

password | string | | Password used to connect Jabber server in gateway-mode.

cert | string | | Full path to PKCS#12 certificate which is used for TLS in server-mode.

cert_password | string | | PKCS#12 certificate password.

admin_jid | JID | | Jabber ID of administrator with admin rights.

admin_password | string | | Administrator password.

enable_privacy_lists | boolean | 1 | True if privacy lists should be enabled.

#### Daemon related settings

Key | Type | Default | Description

----|------|---------|------------

user | string | | Name of user Spectrum switch to if run as daemon.

group | string | | Name of group Spectrum switch to if run as daemon.

pidfile | string | /var/run/spectrum2/$jid.pid | Full path to file to which the pid of Spectrum instance is stored if run as daemon.

working_dir | string | /var/run/spectrum2/$jid | Full path to directory where temporary files and coredumps will be stored if run as daemon.

#### Backends related settings

Key | Type | Default | Description

----|------|---------|------------

backend | string | | Full path to backend executable (for example "/usr/bin/spectrum2_libpurple_backend").

backend_host | string | localhost | Hostname to which backends connets.

backend_port | integer | 10000 | Port on which Spectrum listens for new backends.

users_per_backend | integer | 100 | Maximum number of users per one legacy network backend.

reuse_old_backends | boolean | 1 | True if Spectrum should use old backends which were full in the past.

idle_reconnect_time | time in seconds | 0 | Time in seconds after which idle users are reconnected to let their backend die.

memory_collector_time | time in seconds | 0 | Time in seconds after which backend with most memory is set to die.

protocol | string | | Used protocol in case of libpurple backend (prpl-icq, prpl-msn, prpl-jabber, ...).

### [identity] section

Key | Type | Default | Description

----|------|---------|------------

name | string | Spectrum 2 Transport | Name showed in service discovery.

category | string | gateway | Disco#info identity category. 'gateway' by default.

type | string | | Type of transport ('icq','msn','gg','irc', ...).

### [registration] section

Key | Type | Default | Description

----|------|---------|------------

enable_public_registration | boolean | 1 | True if users are able to register.

language | string | en | Default language for registration form.

instructions | string | Enter your legacy network username and password. | Instructions showed to user in registration form.

username_label | string | Legacy network username: | Label for username field.

username_mask | string | | Example: "$username@gmail.com" - users will register just "my_name" account and transport will connect them to my_name@gmail.com.

auto_register | boolean | 0 | When true, users are registered just by sending presence to transport. Password is set to empty string.

### [database] section

Key | Type | Default | Description

----|------|---------|------------

type | string | none | Database type - "none", "mysql", "sqlite3".

database | string | /var/lib/spectrum2/$jid/database.sql | Database used to store data. Path for SQLite3 or name for other types.

server | string | localhost | Database server.

user | string | | Database user.

password | string | | Database Password.

port | integer | | Database port.

prefix | string | | Prefix of tables in database.

### [logging] section

Key | Type | Default | Description

----|------|---------|------------

config | string | | Full path to log4cxx config file which is used for Spectrum 2 instance

backend_config | string | | Full path to log4cxx config file which is used for backends (if backend supports logging)

---

layout: page

title: Spectrum 2

---

Spectrum 2 uses [log4cxx](http://logging.apache.org/log4cxx/) for logging. In the main config file, there are two options to set full path to log4cxx configuration files which are then used for backends and Spectrum 2 main instance:

	[logging]

	# Full path to config file used for main Spectrum 2 instance logging

	config=/etc/spectrum2/logging.cfg

	# Full path to config file used for backends logging

	backend_config=/etc/spectrum2/backend-logging.cfg

## Log4cxx config files

There is full [documentation of log4cxx on log4cxx homepage](http://logging.apache.org/log4cxx/index.html).

### Logging everything to stdout

For logging to stdout, we have to use ConsoleAppender appender like this:

	# We create two rootLoggers:

	#   - "debug" is internal logger used by log4cxx

	#   - "stdout" is name of our ConsoleAppender logger

	log4j.rootLogger=debug, stdout

	# Create new ConsoleAppender logger with custom PatternLayout

	log4j.appender.stdout=org.apache.log4j.ConsoleAppender

	# Define the output pattern. Characters are mentioned here: http://logging.apache.org/log4cxx/apidocs/classlog4cxx_1_1_pattern_layout.html

	log4j.appender.stdout.layout=org.apache.log4j.PatternLayout

	log4j.appender.stdout.layout.ConversionPattern=%d %-5p %c: %m%n

Configuration options for ConversationPattern are described [here](http://logging.apache.org/log4cxx/apidocs/classlog4cxx_1_1_pattern_layout.html).

### Logging everything to file

	# We create two rootLoggers

	#   - "debug" is internal logger used by log4cxx

	#   - "R" is name of our RollingFileAppender logger

	log4j.rootLogger=debug, R

	# Create new RollingFileAppender logger

	log4j.appender.R=org.apache.log4j.RollingFileAppender

	# Set the filename

	log4j.appender.R.File=/var/log/spectrum2/${jid}/spectrum2.log

	# Set MaxFileSize. Log will be rotated automatically when this limit is reached

	log4j.appender.R.MaxFileSize=10000KB

	# Keep one backup file

	log4j.appender.R.MaxBackupIndex=1

	# Define the output pattern. Characters are mentioned here: http://logging.apache.org/log4cxx/apidocs/classlog4cxx_1_1_pattern_layout.html

	log4j.appender.R.layout=org.apache.log4j.PatternLayout

	log4j.appender.R.layout.ConversionPattern=%d %-5p %c: %m%n

### Logging XML to different file

We have to create another RollingFileAppender to achive this:

	# We create two rootLoggers

	#   - "debug" is internal logger used by log4cxx

	#   - "R" is name of our RollingFileAppender logger for everything except XML

	log4j.rootLogger=debug, R

	# ---- spectrum2.log

	# Create new RollingFileAppender logger

	log4j.appender.R=org.apache.log4j.RollingFileAppender

	# Set the filename

	log4j.appender.R.File=/var/log/spectrum2/${jid}/spectrum2.log

	# Set MaxFileSize. Log will be rotated automatically when this limit is reached

	log4j.appender.R.MaxFileSize=10000KB

	# Keep one backup file

	log4j.appender.R.MaxBackupIndex=1

	# Define the output pattern. Characters are mentioned here: http://logging.apache.org/log4cxx/apidocs/classlog4cxx_1_1_pattern_layout.html

	log4j.appender.R.layout=org.apache.log4j.PatternLayout

	log4j.appender.R.layout.ConversionPattern=%d %-5p %c: %m%n

	# ---- spectrum2_xml.log

	# Define new logger for category Component.XML:

	#   - "debug" is internal logger used by log4cxx

	#   - "XML" is the name of our RollingFileAppender logger for XML category

	log4j.category.Component.XML = debug, XML

	# Do not add XML category into "R" logger, so XML category will be logged only to spectrum2_xml.log, but not to spectrum2.log.

	# If you want to have XML category also in spectrum2.log, set this value to "true"

	log4j.additivity.Component.XML=false

	# Create new RollingFileAppender logger and set the file name

	log4j.appender.XML=org.apache.log4j.RollingFileAppender

	log4j.appender.XML.File=/var/log/spectrum2/${jid}/spectrum2_xml.log

	# Set MaxFileSize. Log will be rotated automatically when this limit is reached

	log4j.appender.XML.MaxFileSize=100000KB

	# Keep one backup file

	log4j.appender.XML.MaxBackupIndex=4

	# Define the output pattern. Characters are mentioned here: http://logging.apache.org/log4cxx/apidocs/classlog4cxx_1_1_pattern_layout.html

	log4j.appender.XML.layout=org.apache.log4j.PatternLayout

	log4j.appender.XML.layout.ConversionPattern=%d %-5p %c: %m%n

### Disable XML logging

	# We create two rootLoggers:

	#   - "debug" is internal logger used by log4cxx

	#   - "stdout" is name of our ConsoleAppender logger

	log4j.rootLogger=debug, stdout

	# Create new ConsoleAppender logger with custom PatternLayout

	log4j.appender.stdout=org.apache.log4j.ConsoleAppender

	# Define the output pattern. Characters are mentioned here: http://logging.apache.org/log4cxx/apidocs/classlog4cxx_1_1_pattern_layout.html

	log4j.appender.stdout.layout=org.apache.log4j.PatternLayout

	log4j.appender.stdout.layout.ConversionPattern=%d %-5p %c: %m%n

	# Disable XML category

	log4j.category.Component.XML = OFF

### Disable logging

To disable logging, you still *must have* one logger created (probably the ConsoleAppender), but you can set log4j.threshold = OFF to not log everything later:

	# We create two rootLoggers:

	#   - "debug" is internal logger used by log4cxx

	#   - "stdout" is name of our ConsoleAppender logger

	log4j.rootLogger=debug, stdout

	# Create new ConsoleAppender logger with custom PatternLayout

	log4j.appender.stdout=org.apache.log4j.ConsoleAppender

	# Define the output pattern. Characters are mentioned here: http://logging.apache.org/log4cxx/apidocs/classlog4cxx_1_1_pattern_layout.html

	log4j.appender.stdout.layout=org.apache.log4j.PatternLayout

	log4j.appender.stdout.layout.ConversionPattern=%d %-5p %c: %m%n

	# Disable logging of everything:

	log4j.threshold = OFF

---

layout: page

title: Spectrum 2

---

## Editing the configuration file

To configure Spectrum 2 to use MySQL database, you have to edit following options in database section:

Section | Key | Type | Change to value | Description

--------|-----|------|-----------------|------------

database| type | string | mysql | Database type - "none", "mysql", "sqlite3", "pqxx".

database| database | string | Name of the already create empty database | Database used to store data.

database| server | string | Database server | Database server.

database| user | string | MySQL user. | MySQL user.

database| password | string | MySQL Password. | MySQL Password.

database| prefix | string | | Prefix of tables in database.

## Creating the database

Spectrum 2 will create the database on the first execution. Once the database is created, you can remove the CREATE TABLE permissions to the MySQL database user you use to connect the SQL.

---

layout: page

title: Spectrum 2

---

## Editing the configuration file

To configure Spectrum 2 to use PostgreSQL database, you have to edit following options in database section:

Section | Key | Type | Change to value | Description

--------|-----|------|-----------------|------------

database| type | string | pqxx | Database type - "none", "mysql", "sqlite3", "pqxx".

database| database | string | Name of the already create empty database | Database used to store data.

database| server | string | Database server | Database server.

database| user | string | PostgreSQL user. | PostgreSQL user.

database| password | string | PostgreSQL Password. | PostgreSQL Password.

database| prefix | string | | Prefix of tables in database.

## Creating the database

Spectrum 2 will create the database on the first execution. Once the database is created, you can remove the CREATE TABLE permissions to the PostgreSQL database user you use to connect the SQL.

---

layout: page

title: Spectrum 2

---

To configure SSL support for Spectrum2 in server mode, you have to generate server-side certificate, convert it to PKCS#12 format and configure path to it in Spectrum 2 config file.

This article describes how to generate self-signed server certificate and use it in Spectrum 2.

### Setup your own CA (Certificate Authority)

	$ openssl genrsa -des3 -out my-ca.key 2048

	$ openssl req -new -x509 -days 3650 -key my-ca.key -out my-ca.crt

### Make a key and a certificate for the server

* When prompted for "Common Name (eg, your name or your server's hostname) []:", add the hostname/JID of your transport (for example "localhost").

* When prompted for "A challenge password []:", *do not* set it.

	$ openssl genrsa -des3 -out spectrum2-server.key 1024

	$ openssl req -new -key spectrum2-server.key -out spectrum2-server.csr

	$ openssl x509 -req -in spectrum2-server.csr -out spectrum2-server.crt -sha1 -CA my-ca.crt -CAkey my-ca.key -CAcreateserial -days 3650

### Convert server key and certficate to PKCS#12 format

When generating pkcs12 file, *do not* set the Export password. Spectrum 2 currently doesn't parse pkcs12 certificates with password.

	$ openssl pkcs12 -export -in spectrum2-server.crt -inkey spectrum2-server.key -out spectrum2-server.p12

### Set path to certificate in config file

Set the path to cert and configure certificate password if you set one for the pkcs12 file.

	[service]

	...

	cert=/etc/spectrum2/certificates/spectrum2-server.p12

---

layout: page

title: Spectrum 2

---

Spectrum 2 consist of several separate parts which cooperates together. This page describes them.

(*!backend.png!*)

## Where are all those things in git-tree?

Directory| Description

---------|------------

./src|Libtransport source codes

./include/transport|Libtransport headers

./plugin/cpp|Libtransport-plugin source codes

./backends/*|Various Spectrum 2 backends source codes

## Libtransport

Libtransport is library providing the high-level interface for creating XMPP transports. It's used by the Spectrum 2 and by several transports.

Libtransport contains NetworkPluginServer class, which acts as server to which backends connect. Libtransport spawns the backend's processes when they are needed (for example when new user logs in) and destroys them when they are not needed anymore (for example when there are no active users on the backend).

Libtransport is used by:

Name| Reason

----|-------

Spectrum 2|It's the Spectrum 2 core

Some backends|Connect the Spectrum2, use of Spectrum 2 database, parsing the config file, ...

Libtransport uses:

 Name| Reason

-----|-------

Swiften library|Connecting to Jabber sever and sending/receiving data from XMPP users

log4cxx|Logging

protobuf|Protocol for libtransport - backends communication

mysql-client|MySQL support

sqlite3|SQLite3 support

pqxx|PostgreSQL support

## Libtransport-plugin

Libtransport-plugin is subset of Libtransport library and contains only basic things for backend development. The goal is to have smaller library with the less dependencies than Libtransport.

The Libtransport-plugin contains NetworkPlugin class, which is the base class for every C++ backend. Programmer has to create his own class inherited from this one and implement all the virtual methods to create new backend.

Libtransport-plugin is used by:

Name| Reason

----|-------

All Backends|Connect the Spectrum 2, parsing the config file

Libtransport-plugin uses:

 Name| Reason

-----|-------

log4cxx|Logging

protobuf|Protocol for libtransport - backends communication

## Spectrum 2

Main Spectrum 2 binary just uses Libtransport and it's core classes to create particular Spectrum 2 instance.

Spectrum2 uses:

Name| Reason

----|-------

Libtransport|Core library...

## Backends

Backends allow communication with particular legacy network and implements things like logging the user in, sending/receiving messages from legacy network and so on. Backend's life-cycle is controlled by the Spectrum 2 (or better said by the Libtransport's NetworkPluginServer class).

Spectrum 2 spawns the backend and gives it `"--host localhost --port 32453"` parameters. Backend then has to connect the Spectrum 2 located at the given host/port and start receiving the commands sent by the Spectrum 2 main instance. For C++, there is wrapper class called NetworkPlugin which does the parsing and allows programmer to code backend just by implementing few virtual methods.

* [Spectrum 2 in gateway mode](tutorials/gateway_mode.html)

* [Configuration file description](configuration/config_file.html)

* [MySQL Support](configuration/mysql.html)

* [PostgreSQL Support](configuration/postgresql.html)

* [Using SSL in server mode](configuration/server_ssl.html)

* [Logging](configuration/logging.html)

* [Backends overview](backends/backends.html)

* [Libpurple backend](backends/libpurple.html)

* [Swiften backend](backends/swiften.html)

* [Libcommuni backend](backends/libcommuni.html)

* [Skype backend](backends/skype.html)

* [Twitter backend](backends/twitter.html)

* [spectrum2_manager tool](management/spectrum2_manager.html)

* [Getting a backtrace](management/getting_backtrace.html)

* [Munin integration](management/munin.html)

* [Spectrum 2 architecture](development/architecture.html)

---

layout: page

title: Spectrum 2

---

If Spectrum is crashing, it’s useful to get backtrace to help us to find the reason. To get a backtrace you have to have debugging symbols installed or compiled Spectrum with them.

## Installing debugging symbols

a) If you are installing from our Debian/Ubuntu repository, you can just install debugging symbols with this command:

	sudo apt-get install spectrum2-dbg libtransport-dbg

*Note:* The debug package has to be in the exact same version as the main package. So your spectrum installation might be upgraded as well when you install these packages.

b) If you build Spectrum by yourself, you have to build it in Debug mode.

	cmake . -DCMAKE_BUILD_TYPE=Debug

	make

	sudo make install

## Installing GDB

	sudo apt-get install gdb

## Getting a backtrace from a coredump

This is preferred method how to get the backtrace, because Spectrum runs without performance issues and once it crashes, it generates a coredump. 

Reproduce the crash and Spectrum will generate the coredump (file named like "core.12345" where the number is Spectrum process ID) in the working_dir (that directory is configurable in config file, default value is /var/lib/spectrum2/$jid/). Now you just have to get the backtrace from the coredump:

	cd /var/lib/spectrum/$jid/userdir

	gdb spectrum2 core.12345

	bt full

## Getting a backtrace by running Spectrum in GDB

This is harder method how to get backtrace and also running Spectrum in GDB brings performance issues. Run Spectrum in GDB:

	gdb --args spectrum2 -n config_name

where "config_name" is name of config you have in /etc/spectrum (You can also specify full path to config instead of its name).

You will see something like this:

	GNU gdb (GDB) 7.0-ubuntu

	Copyright (C) 2009 Free Software Foundation, Inc.

	License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>

	This is free software: you are free to change and redistribute it.

	There is NO WARRANTY, to the extent permitted by law.  Type "show copying"

	and "show warranty" for details.

	This GDB was configured as "i486-linux-gnu".

	For bug reporting instructions, please see:

	<http://www.gnu.org/software/gdb/bugs/>...

	Reading symbols from /home/hanzz/code/test/transport/spectrum...done.

	(gdb)

Now you have to start Spectrum with following GDB command:

	run

Since now Spectrum is running and you have to reproduce the crash or just wait for crash. Then get a backtrace with this GDB command:

	bt full

---

layout: page

title: Spectrum 2

---

Munin is tool for collecting various information from system and showing them in charts. Spectrum 2 contains munin plugin which can be used to generate useful charts in Munin.

### Configuration

There's Munin plugin installed in by default in `/usr/share/munin/plugins/spectrum2_`. You have to create symlinks pointing to that files in `/etc/munin/plugins` name like this:

Symlink name | Meaning

-------------|--------

`spectrum2_uptime` | Uptime

`spectrum2_backends_count` | Backends count

`spectrum2_crashed_backends_count` | Crashed backends count

`spectrum2_online` | Online users count

`spectrum2_messages` | Total messages send over spectrum since the last restart

`spectrum2_messages_sec` | Messages send per second over spectrum transports

`spectrum2_memory` | Memory usage of transports

`spectrum2_average_memory_per_user` | Average memory usage of per user

---

layout: page

title: Spectrum 2

---

Spectrum2 manager is tool for managing Spectrum 2 instances. It can manage local instances and also do some basic management of remote instances.

## Configuration

Spectrum 2 manager normally checks all configuration files (.cfg files) in /etc/spectrum2/transports and do some for Spectrum 2 instances declared there.

This directory can be changed by changing Spectrum 2 manager configuration file, which is stored in /etc/spectrum2/spectrum_manager.cfg by default.

### spectrum_manager.cfg - [service] section:

Key | Type | Default | Description

----|------|---------|------------

config_directory | string | /etc/spectrum2/spectrum_manager.cfg | Directory where Spectrum2 configuration files are stored.

## Managing all local instances

### spectrum2_manager start

Starts all Spectrum2 instances according to config files defined in config_directory. This command can be called repeatedly. It has no effect on already running instances.

### spectrum2_manager stop

Stops all Spectrum2 instances according to config files defined in config_directory.

### spectrum2_manager status

Checks if all local instances (defined in config files in config_directory) are running. Returns 0 if all instances are running. If some instances are not running, returns 3.

### Managing particular Spectrum 2 instance

Spectrum 2 manager can be also used to manage one particular Spectrum 2 instance. For example following command starts Spectrum 2 instance with JID "icq.domain.tld":

	spectrum2_manager icq.domain.tld start

Following command stops that instance:

	spectrum2_manager icq.domain.tld stop

## Querying Spectrum 2 instance

You can get various information from running Spectrum 2 instance. To check all information you can get from Spectrum 2 instance with JID "icq.domain.tld, just run:

	spectrum2_manager icq.domain.tld help

You will get something similar to this list of available commands:

	General:

		status - shows instance status

		reload - Reloads config file

		uptime - returns ptime in seconds

	Users:

		online_users - returns list of all online users

		online_users_count - number of online users

		online_users_per_backend - shows online users per backends

		has_online_user <bare_JID> - returns 1 if user is online

		register <bare_JID> <legacyName> <password> - registers the new user

		unregister <bare_JID> - unregisters existing user

	Messages:

		messages_from_xmpp - get number of messages received from XMPP users

		messages_to_xmpp - get number of messages sent to XMPP users

	Backends:

		backends_count - number of active backends

		crashed_backends - returns IDs of crashed backends

		crashed_backends_count - returns number of crashed backends

	Memory:

		res_memory - Total RESident memory spectrum2 and its backends use in KB

		shr_memory - Total SHaRed memory spectrum2 backends share together in KB

		used_memory - (res_memory - shr_memory)

		average_memory_per_user - (memory_used_without_any_user - res_memory)

		res_memory_per_backend - RESident memory used by backends in KB

		shr_memory_per_backend - SHaRed memory used by backends in KB

		used_memory_per_backend - (res_memory - shr_memory) per backend

		average_memory_per_user_per_backend - (memory_used_without_any_user - res_memory) per backend