more docs

documentation/backends/backends.md

@@ -0,0 +1,28 @@
+---
+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`

documentation/backends/libcommuni.md

@@ -0,0 +1,45 @@
+---
+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.
+

documentation/backends/libpurple.md

@@ -0,0 +1,28 @@
+---
+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
+

documentation/backends/skype.md

@@ -0,0 +1,20 @@
+---
+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

documentation/backends/swiften.md

@@ -0,0 +1,16 @@
+---
+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
+

documentation/backends/twitter.md

@@ -0,0 +1,15 @@
+---
+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

documentation/configuration/config_file.md

@@ -0,0 +1,85 @@
+---
+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)

documentation/configuration/logging.md

@@ -0,0 +1,143 @@
+---
+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
+
+

documentation/configuration/mysql.md

@@ -0,0 +1,21 @@
+---
+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.

documentation/configuration/postgresql.md

@@ -0,0 +1,21 @@
+---
+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.

documentation/configuration/server_ssl.md

@@ -0,0 +1,36 @@
+---
+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

documentation/development/architecture.md

@@ -0,0 +1,76 @@
+---
+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.

documentation/index.md

@@ -15,32 +15,32 @@ title: Spectrum 2
 
 #### Tutorials
 
-* [Spectrum 2 in gateway mode](tutorial_gateway_mode.html)
+* [Spectrum 2 in gateway mode](tutorials/gateway_mode.html)
 
 #### Configuration
 
-* [Configuration file description](config_file.html)
-* [MySQL Support](mysql.html)
-* [PostgreSQL Support](postgresql.html)
-* [Using SSL in server mode](server_ssl.html)
-* [Logging](logging.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
 
-* [Backends overview](backends.html)
-* [Libpurple backend](libpurple.html)
-* [Swiften backend](swiften.html)
-* [Libcommuni backend](libcommuni.html)
-* [Skype backend](skype.html)
-* [Twitter backend](twitter.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)
 
 #### Management
 
-* [spectrum2_manager tool](spectrum2_manager.html)
-* [Getting a backtrace](getting_backtrace.html)
-* [Munin integration](munin.html)
+* [spectrum2_manager tool](management/spectrum2_manager.html)
+* [Getting a backtrace](management/getting_backtrace.html)
+* [Munin integration](management/munin.html)
 
 #### Development
 
-* [Spectrum 2 architecture](developer_arch.html)
+* [Spectrum 2 architecture](development/architecture.html)
 * [Low level backend creation](developer_lowlevel.html)

documentation/management/getting_backtrace.md

@@ -0,0 +1,65 @@
+---
+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

documentation/management/munin.md

@@ -0,0 +1,22 @@
+---
+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
+

documentation/management/spectrum2_manager.md

@@ -0,0 +1,79 @@
+---
+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
+
+