Moving docs to repo

This commit is contained in:
Jan Kaluza 2012-08-20 16:41:37 +02:00
parent 0a5b5b4c20
commit 5e9d48751c
9 changed files with 324 additions and 17 deletions

View file

@ -230,21 +230,11 @@
endif (OPENSSL_INCLUDE_DIR)
include(FindPackageHandleStandardArgs)
if (OPENSSL_VERSION)
find_package_handle_standard_args(OpenSSL
REQUIRED_VARS
OPENSSL_LIBRARIES
OPENSSL_INCLUDE_DIR
FAIL_MESSAGE
"Could NOT find OpenSSL, try to set the path to OpenSSL root folder in the system variable OPENSSL_ROOT_DIR"
)
else (OPENSSL_VERSION)
find_package_handle_standard_args(OpenSSL "Could NOT find OpenSSL, try to set the path to OpenSSL root folder in the system variable OPENSSL_ROOT_DIR"
OPENSSL_LIBRARIES
OPENSSL_INCLUDE_DIR
)
endif (OPENSSL_VERSION)
MARK_AS_ADVANCED(OPENSSL_INCLUDE_DIR OPENSSL_LIBRARIES)
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()

View file

@ -1 +1,2 @@
ADD_SUBDIRECTORY(api)
ADD_SUBDIRECTORY(guide)

32
docs/guide/CMakeLists.txt Normal file
View file

@ -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})

View file

@ -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) |

11
docs/guide/index.textile Normal file
View file

@ -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

130
docs/guide/logging.textile Normal file
View file

@ -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>

15
docs/guide/mysql.textile Normal file
View file

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

View file

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

View file

@ -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>