Moving docs to repo

8 files changed, 317 insertions, 0 deletions

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 370f1366..4349816c 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -1 +1,2 @@
 ADD_SUBDIRECTORY(api)
+ADD_SUBDIRECTORY(guide)
diff --git a/docs/guide/CMakeLists.txt b/docs/guide/CMakeLists.txt
new file mode 100644
index 00000000..b8274dce
--- /dev/null
+++ b/docs/guide/CMakeLists.txt
@@ -0,0 +1,32 @@
+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})
+
diff --git a/docs/guide/config_file.textile b/docs/guide/config_file.textile
new file mode 100644
index 00000000..cb05353a
--- /dev/null
+++ b/docs/guide/config_file.textile
@@ -0,0 +1,74 @@
+
+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) |
diff --git a/docs/guide/index.textile b/docs/guide/index.textile
new file mode 100644
index 00000000..852f7534
--- /dev/null
+++ b/docs/guide/index.textile
@@ -0,0 +1,11 @@
+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
diff --git a/docs/guide/logging.textile b/docs/guide/logging.textile
new file mode 100644
index 00000000..fa1c9640
--- /dev/null
+++ b/docs/guide/logging.textile
@@ -0,0 +1,130 @@
+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>
+
diff --git a/docs/guide/mysql.textile b/docs/guide/mysql.textile
new file mode 100644
index 00000000..8cb20d1d
--- /dev/null
+++ b/docs/guide/mysql.textile
@@ -0,0 +1,15 @@
+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.
\ No newline at end of file
diff --git a/docs/guide/postgresql.textile b/docs/guide/postgresql.textile
new file mode 100644
index 00000000..85d27c0c
--- /dev/null
+++ b/docs/guide/postgresql.textile
@@ -0,0 +1,16 @@
+
+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.
\ No newline at end of file
diff --git a/docs/guide/server_ssl.textile b/docs/guide/server_ssl.textile
new file mode 100644
index 00000000..748d74d5
--- /dev/null
+++ b/docs/guide/server_ssl.textile
@@ -0,0 +1,38 @@
+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>