IF(OPENSSL_INCLUDE_DIR AND OPENSSL_LIBRARIES)

		message(STATUS "Found OpenSSL: ${OPENSSL_INCLUDE_DIR}" ", " ${OPENSSL_LIBRARIES})

		MARK_AS_ADVANCED(OPENSSL_INCLUDE_DIR OPENSSL_LIBRARIES)

	else()

		message(FATAL_ERROR "Could not find OpenSSL: ${OPENSSL_INCLUDE_DIR}" ", " ${OPENSSL_LIBRARIES})

	endif()

ADD_SUBDIRECTORY(guide)

macro(ADD_TEXTILE SRC TITLE)

	MESSAGE(STATUS "Process file: ${SRC}")

	STRING(REGEX REPLACE ".textile\$" "" outfileName "${SRC}")

	SET(outfile "${CMAKE_CURRENT_BINARY_DIR}/${outfileName}.html")

	# Custom command to do the processing

	message(STATUS "FILES" ${outfile})

	if(${ARGN})

		ADD_CUSTOM_COMMAND(OUTPUT "${outfile}"

			COMMAND pandoc -o "${outfile}" "${SRC}" -f textile -t html -s --base-header-level=2 --template=template.html -T "${TITLE}"

			DEPENDS "${SRC}")

	else()

		ADD_CUSTOM_COMMAND(OUTPUT "${outfile}"

			COMMAND pandoc -o "${outfile}" "${SRC}" -f textile -t html -s --toc --base-header-level=2 --template=template.html -T "${TITLE}"

			DEPENDS "${SRC}")

	endif()

	# Finally remember the output file for dependencies

	SET(outFiles ${outFiles} "${outfile}")

endmacro()

ADD_TEXTILE("index.textile" "Spectrum 2 documentation" 1)

ADD_TEXTILE("config_file.textile" "Spectrum 2 - Config File")

ADD_TEXTILE("server_ssl.textile" "Spectrum 2 - Server mode SSL support")

ADD_TEXTILE("mysql.textile" "Spectrum 2 - MySQL Support")

ADD_TEXTILE("postgresql.textile" "Spectrum 2 - PostgreSQL Support")

ADD_TEXTILE("logging.textile" "Spectrum 2 - Logging")

# Setup a target to drive the conversion

ADD_CUSTOM_TARGET(guide ALL DEPENDS ${outFiles})

h2. 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.

h2. [service] section

h3. 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. |

h3. 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. |

h3. 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, ...). |

h2. [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', ...). |

h2. [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. |

h2. [database] section

|_. Key |_. Type |_. Default |_. Description |

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

| database | string | | Database used to store data. |

| server | string | localhost | Database server. |

| user | string | | Database user. |

| password | string | | Database Password. |

| port | integer | | Database port. |

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

h2. [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) |

h2. About

h2. Installing

h2. Configuring

* "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

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:

<pre>

[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

</pre>

h2. Log4cxx config files

There is full "documentation of log4cxx on log4cxx homepage":http://logging.apache.org/log4cxx/index.html.

h3. Logging everything to stdout

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

<pre>

# 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

</pre>

Configuration options for ConversationPattern are described "here":http://logging.apache.org/log4cxx/apidocs/classlog4cxx_1_1_pattern_layout.html

h3. Logging everything to file

<pre>

# 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

</pre>

h3. Logging XML to different file

We have to create another RollingFileAppender to achive this:

<pre>

# 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.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

</pre>

h3. 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:

<pre>

# 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

</pre>

h2. 1. 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. |

h2. 2. 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.

h2. 1. 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. |

h2. 2. 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.

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.

h2. Setup your own CA (Certificate Authority)

<pre>

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

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

</pre>

h2. 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.

<pre>

$ 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

</pre>

h2. 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.

<pre>

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

</pre>

h2. Set path to certificate in config file

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

<pre>

[service]

...

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

</pre>