From 452818d9180b793a91c95bc29553d6d0f9d1fb1d Mon Sep 17 00:00:00 2001 From: Jan Kaluza Date: Tue, 21 Aug 2012 14:47:30 +0200 Subject: [PATCH] docs update --- docs/guide/backends.textile | 22 +++++++ docs/guide/from_source_code.textile | 96 ++++++++++++++++++++++++++++ docs/guide/libcommuni.textile | 42 ++++++++++++ docs/guide/libpurple.textile | 24 +++++++ docs/guide/skype.textile | 17 +++++ docs/guide/spectrum2_manager.textile | 81 +++++++++++++++++++++++ docs/guide/swiften.textile | 13 ++++ 7 files changed, 295 insertions(+) create mode 100644 docs/guide/backends.textile create mode 100644 docs/guide/from_source_code.textile create mode 100644 docs/guide/libcommuni.textile create mode 100644 docs/guide/libpurple.textile create mode 100644 docs/guide/skype.textile create mode 100644 docs/guide/spectrum2_manager.textile create mode 100644 docs/guide/swiften.textile diff --git a/docs/guide/backends.textile b/docs/guide/backends.textile new file mode 100644 index 00000000..a59a5762 --- /dev/null +++ b/docs/guide/backends.textile @@ -0,0 +1,22 @@ +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. + +h2. 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| + +h2. 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| diff --git a/docs/guide/from_source_code.textile b/docs/guide/from_source_code.textile new file mode 100644 index 00000000..14a325c8 --- /dev/null +++ b/docs/guide/from_source_code.textile @@ -0,0 +1,96 @@ +h2. Install Boost and libidn + +You have to have boost-devel and libidn-devel installed before compiling Swiften, otherwise it will compile against bundled version of Boost and libidn and Spectrum compilation will fail. + +h2. Install Swiften from git repository: + +
+git clone git://swift.im/swift
+cd swift
+git checkout swift-2.0beta1
+./scons V=1 swiften_dll=1 Swiften SWIFTEN_INSTALLDIR=/usr/local force-configure=1
+sudo ./scons V=1 swiften_dll=1 Swiften SWIFTEN_INSTALLDIR=/usr/local /usr/local
+
+ +*Note* - If the output of "./scons" command contains following during the configure stage, you don't have boost-devel or libidn-devel installed during the compilation and *Swiften won't work properly*: +
+Checking for C++ header file boost/signals.hpp... no
+....
+Checking for C library idn... no
+
+ +The proper configure script output looks like this: +
+scons: Reading SConscript files ...
+Checking whether the C++ compiler worksyes
+Checking whether the C compiler worksyes
+Checking for C library z... yes
+Checking for C library resolv... yes
+Checking for C library pthread... yes
+Checking for C library dl... yes
+Checking for C library m... yes
+Checking for C library c... yes
+Checking for C library stdc++... yes
+Checking for C++ header file boost/signals.hpp... yes
+Checking for C library boost_signals... yes
+Checking for C++ header file boost/thread.hpp... yes
+Checking for C library boost_thread... no
+Checking for C library boost_thread-mt... yes
+Checking for C++ header file boost/regex.hpp... yes
+Checking for C library boost_regex... yes
+Checking for C++ header file boost/program_options.hpp... yes
+Checking for C library boost_program_options... yes
+Checking for C++ header file boost/filesystem.hpp... yes
+Checking for C library boost_filesystem... yes
+Checking for C++ header file boost/system/system_error.hpp... yes
+Checking for C library boost_system... yes
+Checking for C++ header file boost/date_time/date.hpp... yes
+Checking for C library boost_date_time... yes
+Checking for C++ header file boost/uuid/uuid.hpp... yes
+Checking for C function XScreenSaverQueryExtension()... yes
+Checking for package gconf-2.0... yes
+Checking for C header file gconf/gconf-client.h... yes
+Checking for C library gconf-2... yes
+Checking for C header file libxml/parser.h... no
+Checking for C header file libxml/parser.h... yes
+Checking for C library xml2... yes
+Checking for C header file idna.h... yes
+Checking for C library idn... yes
+Checking for C header file readline/readline.h... yes
+Checking for C library readline... yes
+Checking for C header file avahi-client/client.h... yes
+Checking for C library avahi-client... yes
+Checking for C library avahi-common... yes
+Checking for C header file openssl/ssl.h... yes
+
+ +Note that you have to have at least Python 2.5 to build Swiften. + +h2. Install Google protobuf + +In Fedora, you just have to install following packages: + +
+sudo yum install protobuf protobuf protobuf-devel
+
+ +h2. Install Libpurple for libpurple backend + +You should definitely have latest libpurple, so download Pidgin and compile it, because your distribution probably doesn't have the latest one. + +h2. Install libCommuni for libCommuni IRC backend + +The instructions are defined on "libCommuni wiki":https://github.com/communi/communi/wiki. + +h2. Install Spectrum 2 + +
+git clone git://github.com/hanzz/libtransport.git
+cd libtransport
+cmake . -DCMAKE_BUILD_TYPE=Debug
+make
+
+ +Before running make, check cmake output if the supported features are OK for you. If not, install libraries needed by Spectrum to provide specific feature. + +You can also install spectrum using "sudo make install" diff --git a/docs/guide/libcommuni.textile b/docs/guide/libcommuni.textile new file mode 100644 index 00000000..4a0b6b12 --- /dev/null +++ b/docs/guide/libcommuni.textile @@ -0,0 +1,42 @@ +h2. 1. 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. + +h2. 2. 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. + +h3. 2.1. 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
+
+ +h3. 2.2 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. Currently this mode is not finished yet in Spectrum 2. + +h2. 3. 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. | + diff --git a/docs/guide/libpurple.textile b/docs/guide/libpurple.textile new file mode 100644 index 00000000..e874b6bb --- /dev/null +++ b/docs/guide/libpurple.textile @@ -0,0 +1,24 @@ +h2. Description + +Libpurple backend is backend based on Librpurple library supporting all the networks supported by libpurple + +h2. 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| + diff --git a/docs/guide/skype.textile b/docs/guide/skype.textile new file mode 100644 index 00000000..2d659146 --- /dev/null +++ b/docs/guide/skype.textile @@ -0,0 +1,17 @@ +h2. 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). + +h2. 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
+
diff --git a/docs/guide/spectrum2_manager.textile b/docs/guide/spectrum2_manager.textile new file mode 100644 index 00000000..b2a67e64 --- /dev/null +++ b/docs/guide/spectrum2_manager.textile @@ -0,0 +1,81 @@ +Spectrum2 manager is tool for managing Spectrum 2 instances. It can manage local instances and also do some basic management of remote instances. + +h2. 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. + +h3. spectrum_manager.cfg - [service] section: + +|_. Key |_. Type |_. Default |_. Description | +| config_directory | string | /etc/spectrum2/spectrum_manager.cfg | Directory where Spectrum2 configuration files are stored. | + +h2. Managing all local instances + +h3. 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. + +h3. spectrum2_manager stop + +Stops all Spectrum2 instances according to config files defined in config_directory. + +h3. 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. + +h2. 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
+
+ +h2. 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  - returns 1 if user is online
+    register    - registers the new user
+    unregister  - 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
+
+ + diff --git a/docs/guide/swiften.textile b/docs/guide/swiften.textile new file mode 100644 index 00000000..08c62aaa --- /dev/null +++ b/docs/guide/swiften.textile @@ -0,0 +1,13 @@ +h2. 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. + +h2. Configuration + +You have to choose this backend in Spectrum 2 configuration file to use it: + +
+[service]
+backend=/usr/bin/spectrum2_swiften_backend
+
+