Installing using console installer

Installation using the text-mode installer

When you install Tigase server on a desktop machine or a server having a graphical user interface - you can use the GUI installer. However servers are often administered using SSH text-mode connection because of low connection requirements or user preferences. Because of a popular users demand Tigase development team has decided to implement a console installer for the server.

Note! The console installer is available for the Tigase server from version 4.1.5 and later.

Requirements and and important notice

Before trying the installer please keep in mind:
• This is first - alpha rate version of the text-mode installation - meant to install the server and do some basic configuration. We will be very happy to see bug reports and overall feedback about this feature.
  Please send your remarks to Artur Hefczyc or Mateusz Fiołka
• You will still need to perform some additional steps before running the installer. Main requirement is to download and install Java JDK of minimal 1.6 version. This guide is aimed at advanced users - thus downloading and configuring JDK is left to the reader. You can find more info at the Java downloads site

Download the installer

You can always find the newest Tigase packages in the download section. When you enter the page, you will be presented a list of files to choose from. All Tigase binary packages have conventional names, which help to differentiate them easily. They are of form  tigase-server-x.y.z-bv.ext where 'x', 'y', 'z' and 'v' are version numbers and they change from a release to release. Ext is the file extension which in the case of our console installation program is .jar. We recommend you to download the latest version (highest version number) of the server as it contains latest functions and improvements.

Run the jar file

In terminal (SSH or Windows cmd prompt if you use on) type:

java -jar nameOfTheDownloadedJarFile.jar -console

Installation steps

Now you are ready to to install the server.

Some tips for working with the console installer:
• Please remember to write down your JDK location because you will need to type it during the installation process.
• Installer consists of number of screens which relate to different configuration aspects. Most of the panels end with a question whether you want to redisplay the panel or quit installer. When you make a mistake you will be probably asked later if you want re-enter the data
  again.
• To quit the installer use standard termination key specific to your platform. For example on a Linux system it is the Ctrl+C key combination. Keep in mind that if you quit the installer after it copied some files - it may leave them in the place and you might have to remove them manually.
• In current version the installer is of beta quality and using advanced configuration is not recommended. It might work, however it is not much tested and will be improved later.

Initial screen

On this screen you will find server version info which will be useful if you would to suggest something to Tigase developers.

Welcome to the installation of Tigase XMPP (Jabber) Server
4.1.5-bDEV!
 - Artur Hefczyc

The homepage is at: http://www.tigase.org/
press 1 to continue, 2 to quit, 3 to redisplay

JDK selection

Your system may contain more then one JDK installation, thus you will have to make an explicit decision which one to use. Currently console mode installer doesn't contain any auto-detection code nor validation. You will have to enter the path correctly or you may have problems with running the server. For example
on Ubuntu Linux you can find the JDK in the /lib/jvm/java-6-sun directory. For the current Tigase server JDK of version at least 1.6 is required.

The installed application needs a JDK. A java run-time
environment (JRE) will be not sufficient.

Enter path: /lib/jvm/java-6-sun

Actions selection

Choose whether you want to configure the server in addition to install it.

*** Select what you want to do next:

On this panel you can specify whether you want to install
only or configure already installed server or to do both. If
you are just installing a server on your machine it is a
good idea to do both steps.

-------------------

The wizards you want to execute
Installation of the Tigase Server
[on, off]
on
Configuration of the Tigase Server
[on, off]
on

Installer info

Introduction to the installer.

Please note!

While the Tigase server is quite stable and well tested
application the installer itself is a new addition. Take
precautions especially if you upgrade the server from
earlier version. Backup old server files and the database.

If you notice any problems please report them to address:
Artur Hefczyc

press 1 to continue, 2 to quit, 3 to redisplay

Server info

If you don't know what exactly is Tigase server, you can find some basic introduction on this screen.

Tigase XMPP (Jabber) server ver 4.1.5-bDEV


About

Copyright (C) 2004 Tigase.org. <http://www.tigase.org/>

Tigase Jabber/XMPP Server is
Open Source and Free  (GPLv3)
Java based server. The goals behind the design and
implementation of the server are:


Make the server robust and reliable.
Make the server secure communication platform.
Make flexible server which can be applied to different use
cases.
Make extensible server which takes full advantage of XMPP
protocol extensibility.  

--- Press ENTER to continue ---

Make the server easy to setup and maintain.


Installation, configuration and compilation

The most recent documentation on all these topics is always
available in the project website: www.tigase.org. Please
refer to the website for all the details and always up to
date guides.

You would probably want to start with Quick Start:
http://www.tigase.org/content/quick-start documentation.

The website also contains lots of other useful information
like load tests results, user discussions and on-line support
and help always available to you.

This is 4.1.5-bDEV release of the server. Please include the
exact version number in all correspondence regarding the
server.


press 1 to continue, 2 to quit, 3 to redisplay

Server licence

This is a licence that you have to agree to use Tigase server. Please read it carefully. Take note, that in this manual only part is shown in order to decrease guide length.

Please read the following license agreement carefully:



GNU General Public License - GNU Project - Free Software
Foundation (FSF)


GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007

Copyright (C) 2007 Free Software Foundation, Inc. 
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

Preamble

...
... Fragment cut out
...


You should also get your employer (if you work as a
programmer) or school, if any, to sign a "copyright
disclaimer" for the program, if necessary.  For more
information on this, and how to apply and follow the GNU
GPL, see --- Press ENTER to continue ---

<http://www.gnu.org/licenses/>.

The GNU General Public License does not permit incorporating
your program into proprietary programs.  If your program is
a subroutine library, you may consider it more useful to
permit linking proprietary applications with the library.
If this is what you want to do, use the GNU Lesser General
Public License instead of this License.  But first, please
read

<http://www.gnu.org/philosophy/why-not-lgpl.html>.  

1. I accept the terms of this license agreement.  
2. I do not accept the terms of this license agreement.
Choose number (1-2): 
1
press 1 to continue, 2 to quit, 3 to redisplay 

Server location selection

Enter where do you want the server to be installed. If you have administrator rights you can place it in a standard location where all your applications reside. If you don't have write rights for this place, you can always install the server in your home directory.

Select target path 
[/home/user/tigase] /home/user/tigase-server

press 1 to continue, 2 to quit, 3 to redisplay 1 

Selection of packs to be installed

Some packs are optional and you can disable/enable them. In the following screen they have an [x] option before them. To switch their state enter item number and ENTER. When done press d and ENTER.

Select the packs you want to install:

1 => Base, The base files
2 => Unix Files, Files needed to run the server on Unix like systems
3 => [x] Docs, The documentation
4 => [x] Extras, Extras libraries, MUC, PubSub...
5 => [x] Derby Database, Derby database and JDBC driver
6 => [x] MySQL Database, MySQL JDBC driver (MySQL has to be
installed separately)
7 => [x] PostgreSQL Database, PostgreSQL JDBC driver
(PostgreSQL has to be installed separately)
8 => [x] SQL Server Database, SQL Server JDBC driver (SQL
Server has to be installed separately)
9 => [ ] Sources, The server source files, tools and
libraries sources are not included
r => Redisplay menu
d => Done

Choose action: d
press 1 to continue, 2 to quit, 3 to redisplay

Installation

During extracting and copying server files to their target you will be presented with the process progress.

[ Starting to unpack ]
[ Processing package: Base (1/9) ]
[ Processing package: Unix Files (2/9) ]
[ Processing package: Windows Files (3/9) ]
[ Processing package: Docs (4/9) ]
[ Processing package: Extras (5/9) ]
[ Processing package: Derby Database (6/9) ]
[ Processing package: MySQL Database (7/9) ]
[ Processing package: PostgreSQL Database (8/9) ]
[ Processing package: SQL Server Database (9/9) ]
[ Unpacking finished ]

Basic configuration

This panels contains most important configuration options for the Tigase server. You can choose which components should be configured to be used when running server, add XMPP admin users and enter their password (many admins, comma separated, initially having the same password). Choose different password from the default one. Then select preferred database. If you don't have a standalone DB which you would like to use, you can choose the included Derby DB.

Important notice: Tigase installer doesn't contain the actual databases, only drivers allowing db access. One exception is Derby database, which is included in JDK. It is automatically configured by installer, in case of other databases you will need to configure them by yourself.

*** Basic Tigase server configuration
On this panel you can specify basic configuration settings
for the Tigase server.

Based on your selection here more configuration options
might be presented later on. After the configuration is
complete init.properties file will be created.

You can optionally restart the server at the end of the
process if you like.  

-------------------

0  [x] Default installation
1  [ ] Default plus extra components
2  [ ] Session Manager only
3  [ ] Network connectivity only
input selection:
0
Your XMPP (Jabber) domains [my-laptop] 

Server administrators [admin@my-laptop] 

Admin password [tigase] 

0  [x] Derby (built-in database)
1  [ ] MySQL
2  [ ] PostgreSQL
3  [ ] SQLServer
4  [ ] Other...
input selection:
1

Advanced configuration

Please note: in this version advanced configuration is not supported. Although it may work it has not been tested and thus is not recommended. Please enter off to not use it.

Advanced configuration options
[on, off]
off
press 1 to continue, 2 to quit, 3 to redisplay

Database configuration

Depending on which database you did select, you will be presented with related options to configure its connectivity options. As you will see, the parameters have default values.

*** Database configuration: 

You have selected MySQL database. This database needs
additional configuration parameters. Please enter all
required information.

-------------------

MySQL super user account will be used only to create and
configure database for the Tigase server. It will not be
used by the Tigase server later on.

Super user account name: [root] 

WARNING: password will be visible while entering
Super user password: mysecretpassword 
WARNING: password will be visible while entering
Retype password: mysecretpassword

-------------------

MySQL database details. It will be created automatically if
it does not exist.

Database account: [tigase] 

Account password: [tigase12] 

Database name: [tigasedb] 

Database host or IP: [localhost] 

Additional database parameters: [] 

press 1 to continue, 2 to quit, 3 to redisplay

Database checking and preparation

After entering all database information an automatic test of connection and database setup is performed. If everything is ok installer tries to convert database schema to required version and finally adds XMPP administrators to it.

Performing DB tasks

Checking connection to the database  
Connection OK
Checking if the database exists  
Exists OK
Checking the database schema  
New schema loaded OK
Checking whether the database needs conversion  
Conversion not needed
Adding XMPP admin accounts  
Added admins OK

Installation complete

Now you can run the server and use it.

Install was successful
application installed on /home/user/tigase-server
[ Console installation done ]

Running the sever

You can start the server using the tigase.sh file found in the scripts sub-directory of Tigase server base directory. In the root server directory type the following command:

./scripts/tigase.sh start etc/tigase.conf

Of course if you have a custom config file then change last command appropriately. On a Windows platform you can use a bat file to run the server. There is a run.bat file in the Tigase root directory. Just double click it in Explorer or run it from command line to start the server. A window with server log output will pop-up.

How to check if the server is running

Checking if the server is running is quite easy. Just try to connect to it by using one of may available XMPP clients.

Installation using GUI installer

If you don't want to install Tigase using manual method, you can use the GUI installer. It not only copies server files to preferred place, but also assists with configuration of the most important parameters and database setup. Therefore it is the preferred way to install Tigase.

Prerequisites

Before you can start the GUI installer you will need to have working Java environment. Although installer only requires JRE (Java Runtime Environment), server needs the JDK (Java Development Kit). Please do note that currently minimal JDK version Tigase is capable to run on is 1.6. If you don't have JDK installed it is the right moment to do it. Visit the 4Java downloads site From the list of available packages select newest JDK version (if you don't have a specific need to use J2EE then choose a package without it). After configuring JDK you can download the Tigase GUI installer and start the server installation process. It is also important to set the JAVA_HOME environment correctly.

Download the installer

You can always find the newest Tigase packages in the 5download section. When you enter the page, you will be presented a list of files to choose from. You may be sceptic at the beginning as there are lot of choices, but you don't have to. All Tigase binary packages have conventional names, which help to differentiate them easily. They are of form  tigase-server-x.y.z-bv.ext where 'x', 'y', 'z' and 'v' are version numbers and they change from a release to release. Ext is the file extension which in the case of our GUI installation program is .jar. We recommend you to download the latest version (highest version number) of the server as it contains latest functions and improvements.

Run the jar file

On most systems installing JRE or JDK creates a default association which allows to run the .jar file by just clicking/ double clicking on it. However if nothing happens when you do it there is a way to do it manually. Perform the steps in the following order:

1. If you are on Windows system you can use the command prompt to run the installer directly using the java command.
   1. Click on the Start menu and choose the Run action (You can also use the Win+R shortcut).
   2. You will be presented with a dialog box where you can enter a command. Type "cmd" (or "command" in the case of windows version older then 2000) and submit the window.

   If you are on a Linux system, you can use a terminal. It should be easily discoverable as it is a standard tool on this platform. Find and run it.

2. Command prompt / terminal will appear. You will be able to check a whether your Java environment is working. To do it type the
   

   java -version

   command and press Enter. If the message says that the command is not recognised then your Java installation may be corrupt or not configured properly. For correctly setting up JRE/JDK including setting the JAVA_HOME environmental variable please check documentation provided on the JDK download site. Also when the command succeeds please check if the printed version number fulfils Tigase requirements. When many versions of JDK/JRE are installed on one machine java command will need to be invoked with the full path it is placed on.

3. When you have no doubt that you can run the correct java launcher, you may start the installer i.e. for the file tigase-server-4.1.0-b1315.jar downloaded to the c:\download directory type the following command:
   

   java -jar c:\download\tigase-server-4.1.0-b1315.jar

   This command should start the installer or print an error message explaining what is the cause of problem.

Starting the installation

Please note that this tutorial does cover only basic installation mode. Some screens have been omitted because they contain advanced options which are not shown in simple installation mode. Other such as progress of copying files and summary info are on the other hand self explanatory and will also not described.

JDK selection

6

This screen is only shown when JDK has not been selected automatically. When your JAVA_HOME path is properly set, it will be auto-detected saving you some configuration time. If you are reading this step and still don't have JDK installed, then go back to the 7prerequisites section where you can find some info on how to prepare your system for Tigase installation. Sometimes your system will be configured in a way that prevents detection of JDK path. This often happens when you install JRE after installing JDK. You will have to find JDK directory yourself. It is by default installed in the Program Files\Java directory of your system drive.

Installation type selection

8

Recommended practice is to choose both installation and configuration of the server as manual configuration is more complicated, time consuming and error-prone.

Introduction to the server

9

This screen shows some information about Tigase which may help you understand what it is and how it can help to take advantage of the XMPP protocol. It is important that you read all information's appearing on the installer screens, as they contain valuable hints and most recent information.

Choice of base directory

10

This is the point where you choose where do you want you server to be installed. Recommended path should not contain spaces, as it may be reason of some strange path problems. In the case of installation on Windows it should be installed on a short path because there is a limit of path lengths. Also note that on Windows Vista there may be some problems with making the server work while installed in the Program Files directory, related to the working of UAC mechanism, so better don't install it there. If you don't want are unsure about where to place the server, you can always leave the default selection.

Packages selection

11

Next important step is package selection. Some choices are grey and you cannot change them as they are essential. All of the rest is optional. It consists of documentation, database drivers, sources of the server and some extras. When you select an item, you will be presented with a short description of it's content.

We recommend you to install documentation. It contains valuable resources which may be very helpful in administration and general use of the server.

If you have a working database platform that you want to use for storing all important user information in, just select appropriate db drivers. If you don't have a database engine, you can use the included derby along with also included drivers.

If you are a developer and you want to be able to check how the server is working or you want to help with the development, you can install also the included source codes.

Basic server configuration

12

On this screen you will find most important basic configuration options. As this guide covers only non-advanced set up - disable the advanced configuration checkbox.

You can select which components will be installed. For most installations default selection will most appropriate. You can expand the list to check if any of the other options will better suit your needs.

It is very important that you enter your domain name correctly here.

• On Linux like system you can use the hostname command and extract the domain part from the output. If you use the -f parameter then you will get the fully qualified domain name.
• On Windows use the standard System control panel applet. You will find your domain (computer name) in the Computer name tab.

On the other hand if you want to use Tigase virtual domain support and you have your DNS system configured properly, then you can put your virtual domains list here. Just separate them by comma characters. For example if your server is seen from the outside as veloci.tigase.org, mammoth.tigase.org and tigase.org then you can use Tigase instance as if it were three separate instances. In reality it will be one server, however admin@veloci.tigase.org will be a different user then admin@tigase.org. This feature allows to use one server for separating user groups, for example different organizations.

When you will have your domain name just enter it in the domain text box. Next parameter will be the JID of server administrator. Standard practice is to give him name of admin, however you may choose any name you like. For example for domain tigase.org full admin name would be admin@tigase.org. Just stick your chosen name and domain together using the @ character as separator.

Starting from this version your XMPP admin will be automatically added to the database, so after installation you can just login into the server without registering admin manually.

You should also select a database which will be used for storing user info. Default is the Derby database, if you don't need anything special just leave it as it is. Just select a new password as the default one may be easy to guess for a hacker.

Important notice: Tigase installer doesn't contain the actual databases, only drivers allowing db access. One exception is Derby database, which is included in JDK. It is automatically configured by installer, in case of other databases you will need to configure them by yourself.

Verification of database connection and performing DB tasks

13

When you switch to this screen an automatic test of database configuration will be started. It consists of few steps which will be executed in order. After testing connection and configuring schema, admin users will be added.

What to do if any of the tests will fail?

• If you decided to use your own database, check if you entered correct password and whether your database is running.
• If you use the embedded Derby database then probably your problem is more complicated. An error may indicate a bug in the installer. You may report it to one of Tigase developers.

If you cannot go beyond this step after trying to resolve database problems you may try manual installation mode.

Finishing installation

When you perform all those steps altogether with choosing Start Menu location and other basic actions you will be informed that installation process is complete. You can now use your Tigase server. There are some post installation actions you may want to perform. They are briefly presented below.

Running the sever

Part of the installation process is selection of Tigase base directory. This is where you can find all important server files. Installer will create some configurable shortcuts in the Start Menu. You can navigate to the menu and use it to start the server. To run the server manually:

• On a Linux system you may start the server using the tigase.sh file found in the scripts sub-directory of Tigase server base directory. In the root server directory type the following command:

  ./scripts/tigase.sh start etc/tigase.conf

  Of course if you have a custom config file then change last command appropriately.

• On a Windows platform you can use a bat file to run the server. There is a run.bat file in the Tigase root directory. Just double click it in Explorer or run it from command line to start the server. A window with server log output will pop-up.

14

Installation as a service

On Windows you can install Tigase as a service. To do it use the InstallTigaseService.bat batch file found also in server root directory.

In this mode service will be running in background and will be controllable from the Services management snapshot. To launch the tool right click on the Computer icon on the desktop. Choose the Manage action. It will run the Computer management graphical configuration program. On the left side choose the Services item. You will be shown with a list of services. Here you can find Tigase service when it will be installed.

To uninstall Tigase service use the UninstallTigaseService.bat file from Tigase server root directory.

How to check if the server is running

Checking if the server is running is quite easy. Just try to connect to it by using one of may available XMPP clients.

Manual installation in console mode

Our preferred way to install the Tigase server is using GUI installer and configuration program which comes with one of the binary packages. Please pick up the latest version of the JAR file in our download section.

In many cases however this is not always possible to use the GUI installer. In many cases you have just an ssh access or even a direct access in console mode only. We are going to provide a text-only installer in one of the next releases but for the time being you can use our binary packages to install the server manually. Please continue reading to learn how to install and setup the server in a few easy steps...

If you have an old version of the Tigase server running and working and you intend to upgrade it please always backup the old version first.

Get the binary package

Have a look at our download area. Always pick the latest version of the package available. For manual installation either zip or tar.gz file is available. Pick one of files with filename looking like: tigase-server-x.y.z-bv.tar.gz or tigase-server-x.y.z-bv.zip where 'x', 'y', 'z' and 'v' are version numbers and they change from a release to release.

Unpack the package

Unpack the file using command for the tar.gz file:

 $ tar -xzvf tigase-server-x.y.z-bv.tar.gz

or for the zip file:

 $ unzip tigase-server-x.y.z-bv.zip

A new directory will be created: tigase-server-x.y.z-bv/.

Sometimes after unpacking package on unix system startup script doesn't have execution permissions. To fix the problem you have to run following command:

 $ chmod u+x ./scripts/tigase.sh

Prepare configuration

If you look inside the new directory, it should like this output:

 $ ls -l
total 316K
-rw-r--r--  1 265K 2008-12-15 22:24 ChangeLog
-rw-r--r--  1  37K 2008-12-15 22:24 License.html
-rw-r--r--  1 1.1K 2008-12-15 22:24 README
drwxr-xr-x  6  204 2009-02-03 13:25 certs/
drwxr-xr-x 22  748 2009-02-03 13:25 database/
drwxr-xr-x  3  102 2008-12-15 22:24 docs/
drwxr-xr-x  4  136 2009-02-03 13:25 etc/
drwxr-xr-x  3  102 2009-02-03 13:25 jars/
drwxr-xr-x 12  408 2009-02-03 13:25 libs/
drwxr-xr-x  2   68 2008-12-15 22:24 logs/
-rw-r--r--  1 1.5K 2008-12-15 22:24 package.html
drwxr-xr-x  7  238 2009-02-03 13:25 scripts/

At the moment the most important is the etc/ directory with 2 files:

 $ ls -l etc/
total 8.0K
-rw-r--r-- 1  97 2008-12-15 22:24 init.properties
-rw-r--r-- 1 333 2008-12-15 22:24 tigase.conf

Small change in the tigase.conf file is needed. Find a line setting correct JAVA_HOME:

JAVA_HOME="${JDKPath}"

and replace ${JDKPath} with a path to Java installation on your system.

You need also to edit the init.properties file. It contains initial parameters normally set by the configuration program. As you do the installation manually you have to edit this file yourself. It contains already a few lines:

 $ cat etc/init.properties 
config-type=--gen-config-def
--admins=admin@$HOST_NAME
--virt-hosts = $HOST_NAME
--debug=server

 You have to replace $HOST_NAME with a domain name used for your XMPP (Jabber) installation. Let's say this is 'jabber.your-great.net'. Your init.properties should look like this then:

 $ cat etc/init.properties 
config-type=--gen-config-def
--admins=admin@jabber.your-great.net
--virt-hosts = jabber.your-great.net
--debug=server

You can also use multiple virtual domains if you want. Please have a look at the detailed description for --virt-hosts property in the init.properties guide and also more detailed information in the Virtual Hosts in the Tigase Server guide.

Unfortunately this is not all. You also need to configure connection to the database. First you have to decide what database you want to use: Derby, MySQL or PostgreSQL. Then there are to more properties you have to add to the init.properties: --user-db and --user-db-uri. The first property specifies the database type you use and the second the database connection string. For simplicity let's assume you want to use Derby database with files located in directory /var/lib/tigase/derby. 2 more lines need to be added to the init.properties file:

 $ cat etc/init.properties 
config-type=--gen-config-def
--admins=admin@jabber.your-great.net
--virt-hosts = jabber.your-great.net
--debug=server
--user-db=derby
--user-db-uri=jdbc:derby:/var/lib/tigase/derby

This is enough basic configuration to have your Tigase server installation running.

Prepare database

Normally the database is prepared for you during the installation process. Now you are on your own. As in section above we prepare your first installation to run with the Derby database. Creating and preparing the Derby database is actually quite easy if you use a helper script: ./scripts/derby-db-create.sh. The file might not be in your scripts/ directory if you have an earlier version of the package. Simply download it from the link provided if it is missing and put it in the scripts/ directory and execute it with the database location as the parameter:

 $ ./scripts/derby-db-create.sh /var/lib/tigase/derby

There will be lots of output but if there is no error at the end of the output it means your database has been created and it is ready to use and you are ready to....

There might be filesystem access restrictions for the directory: /var/lib/ and you might want/need to select a different location.

Start the server

Starting the server is the easiest part. Simply execute following command:

 $ ./scripts/tigase.sh start etc/tigase.conf

 and you should get the output like this:

Starting Tigase: 
nohup: redirecting stderr to stdout
Tigase running pid=18103

Check if it is working

The server is started already but how do you know if it is really working and there were no problems. Have a look in the logs/ directory. There should be a few files in there:

 $ ls -l logs/
total 40K
-rw-r--r-- 1 20K 2009-02-03 21:48 tigase-console.log
-rw-r--r-- 1 16K 2009-02-03 21:48 tigase.log.0
-rw-r--r-- 1   0 2009-02-03 21:48 tigase.log.0.lck
-rw-r--r-- 1   6 2009-02-03 21:48 tigase.pid

 2 first files are the most interesting for us: tigase-console.log and tigase.log.0. The first one contains very limited information and only the most important entries. Have a look inside and check if there are any WARNING or SEVERE entries. If not everything should be fine.

Now you can connect with a Jabber (XMPP) client of your choice. The first thing to do would be registering the first account - the admin account from your init.properties file: admin@jabber.your-great.net. Refer to your client documentation how to register a new account.

Tigase server binary updates

Most projects try to make sure that the SVN trunk code always compiles correctly. In the Tigase server case this is not enough however. Lots of installations out there we know of run just straight from out SVN trunk line. This puts on us an extra responsibility. Therefore our general approach is to run all functional tests before each code commit to ensure it works correctly. Of course this does not guarantee it will work correctly and efficiently in all cases and on all systems.

Some people like to be on the bleeding edge and always use the source code repository trunk some others prefer to stick to stable public releases. There is however a lot of other who would like to be able to use something from the middle - have the most recent features and new bug fixes but at least in "Beta" or "Release-Candidate" state.

If you look at the Monitor on the right hand side of the Tigase website you can see that the currently running version is always higher then the version available for download. If you are interested to update your server to the more recent version without much hassle please continue to read.

Installing Tigase from the public binary packages is pretty straightforward especially if you use the installer. Using SVN trunk sources to compile them for your own installation is not simple thing, however people who decide to do so normally don't need much help or instructions. This document describes how to update your system using so called Betas or RC versions we release from time to time.

For releasing our Betas or RC versions we use Maven tool. All our projects and packages are always available in the Tigase Maven repository. You can find there both sources, documentation and binary packages ready to download and use.

If you look for example into the Tigase server directory you can see a list of versions already published. The version with SNAPSHOT in name is something we are working on right now or we used to work in the past. The code used to generate the version is very close to what is in SVN repository.

Therefore if you want to use the most recent SVN code but don't want to compile it yourself you can download the most recent SNAPSHOT and replace your current libraries with it. Please note there might be many snapshots for a single version number. Just pick the last one. The file name consists of the version number, the creation date, creation time and snapshot number: tigase-server-4.1.1-20090211.142252-8.jar

Those who are interested in using more stable version should pick the most recent version without the SNAPSHOT in its name. There is always only one binary release for each final version. Looking in the version directory you can find 2 more binary files for each final version: one with documentation and another with source codes. Each final release is also tagged in our SVN repository so you can checkout or browse the source code if you need. There is a nicer source code browser available too.

A few things to remember when you do the update from our maven repository:

1. If you update to the most recent version of the server you MUST also update all libraries to the most recent version and you MUST also update all other elements like MUC and PubSub. Only this way you can be sure all parts are compatible with each other and will work correctly.
2. Please make sure you REPLACE old libraries with new files. A common mistake is to copy new libraries to a directory and leave old files too. This leads to unpredictable problems. Note, tigase server library for example is stored in jars/tigase-server.jar file. From the repository however you would download: tigase-server-4.1.4.jar file. Make sure you don't have both loaded at runtime.

The instruction may not be accurate or complete. If you run in to any problems or find something wrong with the instruction please let me know. I am always open for suggestions and comments.

Configuration

The main and actually the only configuration for the Tigase server is kept in the XML file. Let's call it tigase.xml for further discussion.

When the user tries to setup the client for the first time he comes across 2 other configuration files: tigase.conf and init.properties which might be confusing. Here is a brief explanation what all those files are about and in other sections you can learn all the details needed to configure the server.

1. tigase.xml is the only Tigase server configuration file. It stores all the runtime settings and if it is missing the server generates a new file with whole configuration with some default settings + settings read from the init.properties file. You may edit the file manually to adjust settings but this is not recommended as manual editing the XML is error prone. Another way of changing this file and changing the configuration is to use ad-hoc commands which allow you to modify configuration at run-time and cause updating the XML file too. Ad-hoc commands method is not polished yet thus it is also not recommended. The safest way to tweak server runtime parameters is to put them in the init.properties file.
2. init.properties file is a simple text file with server parameters in form: key = value. When the XML configuration file is missing the Tigase server reads init.properties file and uses parameters found there as defaults for generation of the XML file. Therefore if you change the init.properties file you normally have to stop the server, remove the XML file and start the server again. All the settings from the init.properties are read and applied to the XML configuration. The properties file is easy to read and very safe to modify. At the moment this is the recommended way change the server configuration.
3. tigase.conf is the Tigase server startup configuration. It is actually not used by the server itself. It rather contains operating system settings and environment parameters to correctly run the Java Virtual Machine. It is only useful on the unix-like systems with Bash shell. If you run the server on MS Windows systems tigase.bat and wrapper.conf files are used instead. The tigase.conf file is read and loaded by the scripts/tigase.sh shell script which also scans the operating system environment for Java VM and other tools needed.

vhosts=test-a, test-b, test-c
vhosts : test-a, test-b, test-c
    vhosts     =     test-a, test-b, test-c

<component name="bosh">
  <node name="5280">
   <map/>
   <node name="tls">
    <map>
     <entry type="String" key="allow-invalid-certs" value="false"/>
    </map>
   </node>
  </node>
</component>

bosh/5280/tls/allow-invalid-certs = false 

ssender/games-list-updater/interval[L]=60

<tigase-config>
  <component name="basic-conf">
    .... settings
  </component>
  <component name="message-router">
    .... settings
  </component>
</tigase-config>

<map>
   <entry value="localhost" type="String" key="remote-host"/>
   <entry value="false" type="Boolean" key="demo-mode"/>
   <entry value="1000" type="Integer" key="max-queue-size"/>
   <entry type="String[]" key="hostnames">
      <item value="test-a"/>
      <item value="localhost"/>
   </entry>
   <entry type="int[]" key="ports">
      <item value="5222"/>
      <item value="5223"/>
   </entry>
</map>

<component name="c2s">
  <map>
    <entry type="String[]" key="hostnames">
      <item value="test-d"/>
      <item value="localhost"/>
    </entry>
  </map>
  <node name="connections">
    <map>
      <entry type="int[]" key="ports">
         <item value="5222"/>
         <item value="5223"/>
      </entry>
    </map>
    <node name="5222">
      <map>
         <entry value="localhost" type="String" key="remote-host"/>
         <entry value="plain" type="String" key="socket"/>
         <entry value="accept" type="String" key="type"/>
      </map>
    </node>
  </node>
</component>

ENC="-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8"
DRV="-Djdbc.drivers=org.postgresql.Driver"
JAVA_OPTIONS="${ENC} ${DRV} -server -Xms100M -Xmx100M "
CLASSPATH=""
TIGASE_CONFIG="tigase-pgsql.xml"
TIGASE_OPTIONS=" --property-file etc/init.properties "

Prepare the MySQL database for the Tigase server

This guide describes how to prepare the MySQL database for connecting the Tigase server to it.

Basic setup

The MySQL database can be prepared in many ways. Most of Linux distributions contain tools which allow you to go through all steps from the shell command line. To make sure, however it works on all platforms the same way I show first how to do it under MySQL command line client.

Configuring from MySQL command line tool

Run the MySQL command line client in either Linux or MS Windows environment and enter following instructions:

1. Create the database for the Tigase server:
   

   mysql> create database tigasedb;
   

2. Add the tigase_user user and grant him access to the tigasedb database. Depending on how you plan to connect to the database (locally or over the network) use one of following commands or all if you are not sure:
   Grant access to tigase_user connecting from any network address.

   mysql> GRANT ALL ON tigasedb.* TO tigase_user@'%'
                   IDENTIFIED BY 'tigase_passwd';
   

   Grant access to tigase_user connecting from localhost.

   mysql> GRANT ALL ON tigasedb.* TO tigase_user@'localhost'
                   IDENTIFIED BY 'tigase_passwd';
   

   Grant access to tigase_user connecting from local machine only.

   mysql> GRANT ALL ON tigasedb.* TO tigase_user
                   IDENTIFIED BY 'tigase_passwd';
   

   For the Tigase server version 4.x additional permissions must be granted for the database user:

   mysql> GRANT SELECT, INSERT, UPDATE ON mysql.proc TO 'tigase_user'@'localhost';
   mysql> GRANT SELECT, INSERT, UPDATE ON mysql.proc TO 'tigase_user'@'%';
   mysql> GRANT SELECT, INSERT, UPDATE ON mysql.proc TO 'tigase_user';
   
   

   And now you can update user permission changes in the database:

   mysql> FLUSH PRIVILEGES;
   

3. Load database schema to initialize the Tigase server database space. First, switch to the database you have just created:
   

   mysql> use tigasedb;
   

   Assuming you run the mysql client in Linux from the Tigase installation directory. If you run the Tigase server all versions below 4.0:

   mysql> source database/mysql-schema.sql;
   

   For the Tigase server version 4.x you have to use proper schema version:

   mysql> source database/mysql-schema-4.sql;
   

   On Windows you have probably to enter the full path:

   mysql> source c:/Program Files/Tigase/database/mysql-schema.sql;
   

   The initialization schema file should be also available locally in database/ directory of your Tigase installation.

Configuring from the Linux shell command line

Follow steps below to prepare the MySQL database:

1. Create the database space for the Tigase server:
   

   mysqladmin -p create tigasedb
   

2. Add the tigase_user user and grant him access to the tigasedb database. Depending on how you plan to connect to the database (locally or over the network) use one of following commands or all if you are not sure:
   Grant access to tigase_user connecting from any network address.

   echo "GRANT ALL ON tigasedb.* TO tigase_user@'%' \
                   IDENTIFIED BY 'tigase_passwd'; \
                   FLUSH PRIVILEGES;" | mysql -u root -pdbpass mysql
   

   Grant access to tigase_user connecting from localhost.

   echo "GRANT ALL ON tigasedb.* TO tigase_user@'localhost' \
                   IDENTIFIED BY 'tigase_passwd'; \
                   FLUSH PRIVILEGES;" | mysql -u root -pdbpass mysql
   

   Grant access to tigase_user connecting from local machine only.

   echo "GRANT ALL ON tigasedb.* TO tigase_user \
                   IDENTIFIED BY 'tigase_passwd'; \
                   FLUSH PRIVILEGES;" | mysql -u root -pdbpass mysql
   

3. Load database schema to initialize the Tigase server (version below 4.0) database space:
   

   mysql -u dbuser -p tigasedb < mysql-schema.sql
   

   For the Tigase server version 4.0 and later:

   mysql -u dbuser -p tigasedb < mysql-schema-4.sql
   

   The initialization schema file should be also available locally in database/ directory of your Tigase installation.

Configuring MySQL for UTF-8 support

In the my.conf put following lines:

[mysql]
default-character-SET=utf8
[client]
default-character-SET=utf8
[mysqld]
init_connect='SET collation_connection = utf8_general_ci; SET NAMES utf8;'
character-set-server=utf8
default-character-SET=utf8
collation-server=utf8_general_ci
skip-character-set-client-handshake

Then connect to the database and from the command line shell check settings:

SHOW VARIABLES LIKE 'character_set_database';
SHOW VARIABLES LIKE 'character_set_client';

If any of these shows something else then 'utf8' then you have to correct it:

ALTER DATABASE tigasedb DEFAULT CHARACTER SET utf8;

You can now also test your database installation if it accepts UTF-8 data. Best way is just to create an account with UTF-8 characters:

call TigAddUserPlainPw('żółw@some.domain.com', 'żółw');

And then check of the account has been created:

SELECT * FROM tig_users WHERE user_id = 'żółw@some.domain.com';

If the last command gives you no results it means there is still something wrong with settings. You might also check you shell settings to make sure your command line shell supports UTF-8 characters and passes them correctly to MySQL:

export LANG=en_US.UTF-8
export LOCALE=UTF-8
export LESSCHARSET='utf-8'

It seems to me that MySQL 5.0.x also needs an extra parameters in the connection string: '&useUnicode=true&characterEncoding=UTF-8' while MySQL 5.1.x seems to not need it but it doesn't hurt to have it for both versions. You have to edit 'etc/init.properties' file and append this to the database connection string.

For MySQL 5.1.x, however, you need also updated code for all database stored procedures and functions used by the Tigase. They are updated for Tigase version 4.4.x and up, for the time being if you use older version of the Tigase server you can reload stored procedures using the file from SVN.

 Other MySQL setting worth considering

There is a number of other options useful, especially for a performance reasons. Please note, you have to review them as some of them may impact data reliability and are useful for performance or load tests installations only.

# InnoDB seems to be a better choice
# so lets make it a default DB engine
default-storage-engine = innodb

Some the general MySQL settings which mainly affect performance:

key_buffer           = 64M
max_allowed_packet   = 32M
sort_buffer_size     = 64M
net_buffer_length    = 64K
read_buffer_size     = 16M
read_rnd_buffer_size = 16M
thread_stack         = 192K
thread_cache_size    = 8
query_cache_limit    = 10M
query_cache_size     = 64M

InnoDB specific settings:

# Keep data in a separate file for each table
innodb_file_per_table           = 1
# Allocate memory for data buffers
innodb_buffer_pool_size         = 1000M
innodb_additional_mem_pool_size = 100M
# A location of the MySQL database
innodb_data_home_dir            = /home/databases/mysql/
innodb_log_group_home_dir       = /home/databases/mysql/
# The main thing here is the 'autoextend' property
# without it your data file may reach maximum size and
# no more records can be added to the table.
innodb_data_file_path           = ibdata1:10M:autoextend
innodb_log_file_size            = 10M
innodb_log_buffer_size          = 32M
# Some other performance affecting settings
innodb_flush_log_at_trx_commit  = 2
innodb_lock_wait_timeout        = 50
innodb_thread_concurrency       = 16

I am certainly not a database expert nor MySQL expert and I do not pretend to be one. So any comments or suggestions you may have are very welcome and appreciated.

Debuging Tigase

If something goes wrong and you can't find out why it is not working as you expect you might want more detailed debugging options switched on.

Tigase is a Java application and it uses Java logging library this gives you flexibility to switch logging on for selected java package or even for a single Java class.

Logs files are stored in logs/ directory. tigase-console.log keeps all the data but only basic logs. tigase.log.N files keep all the detailed logging entries. So this is the place where you should look in case of problems.

The easy way - init.properties file

The easiest way to change logging for the Tigase package is modifying in init.properies following line:

--debug=server

The line above says: "Switch on ALL debug messages for packet: tigase.server". The tigase.server packet keeps all component's classes. So it allows you to monitor what is going on in each component. What packets it receives and what it is sending out.

Usually people want to see what is going on the network level. That is what has been sent and what has been received by the server - the actual character data. The class which would print all received and sent character data is: tigase.xmpp.XMPPIOService. To enable all debugging info for this class you have to modify the debug line:

--debug=xmpp.XMPPIOService

Note, you skip the tigase. part.

You can also have debugging switched on for many packages/classes at the same time:

--debug=server,xmpp.XMPPIOService

Other packages you might be interested in are:

• tiagse.io and tigase.net which can print out what is going on a very low level network level including TLS/SSL stuff.
• tigase.xml would print the XML parser debugging data.
• tigase.cluster would print all the clustering related stuff. So if you have clustered installation you might be interested in debug settings:
  

  --debug=server,cluster
  

• tigase.xmpp.impl would print logs from all plugins loaded to the Tigase server.

and so on...

This method, however has 2 main disadvantages:

1. You have to remove your XML config file and regenerate it which might be inconvenient.
2. You can't set logging this way for classes and packages other than tigase. package. And this might be a problem if you include your own code in and load it into the server.

The more difficult but more powerful - tigase.xml file

If you want to modify debugging settings without regenerating the whole XML config file you can modify it yourself manually and add debug entries. This must be done very carefully or you break the XML file and configuration won't work.

Anyway. Open the XML config file with some good text editor (or XML editor) and find the line:

<node name="logging">

Below is a long list of all logging settings. One of them is:

<entry value="INFO" type="String" key=".level"/>

Which says: INFO debug level for all the code. This level gives you very little debugging information. Therefore for example your init.properties line --debug=server adds one extra line in there:

<entry value="ALL" type="String" key="tigase.server.level"/>

I think now everything should be clear. You need to add a similar line changing only "key" attribute. If you need to switch logging on for a specific class - tigase.xmpp.XMPPIOService for example, add:

<entry value="ALL" type="String" key="tigase.xmpp.XMPPIOService.level"/>

You can also put there your own package or class name. After you changed the config file you have to restart the server.

Note, don't overdose the debugging or your logs are full of trash you can read.

Importing user data

You can easily copy data between Tigase compatible repositories that is repositories for which there is a database connector. It is not that easy however to import data from an external source. Therefore a simple data import functionality has been added to repository utilities package.

You can access repository utilities through command ./bin/repo.sh or ./scripts/repo.sh depending on whether you use binary package or source distribution.

-h parameter gives you a list of all possible parameters:

./scripts/repo.sh -h

Parameters:
 -h          this help message
 -sc class   source repository class name
 -su uri     source repository init string
 -dc class   destination repository class name
 -du uri     destination repository init string
 -dt string  data content to set/remove in repository
 -u user     user ID, if given all operations are only for that ID
             if you want to add user to AuthRepository parameter must
             in form: "user:password"
 -st         perform simple test on repository
 -at         simple test for adding and removing user
 -cp         copy content from source to destination repository
 -pr         print content of the repository
 -n          data content string is a node string
 -kv         data content string is node/key=value string
 -add        add data content to repository
 -del        delete data content from repository
 ------------
 -roster     check the user roster
 -aeg [true|false]  Allow empty group list for the contact
 -import file  import user data from the file of following format:
         user_jid, password, roser_jid, roster_nick, subscription, group



Note! If you put UserAuthRepository implementation as a class name
      some operation are not allowed and will be silently skipped.
      Have a look at UserAuthRepository to see what operations are
      possible or what operation does make sense.
      Alternatively look for admin tools guide on web site.

The most critical parameters are source repository class name and initialization string. Therefore there are a few example, preset parameters which you can use an example and adjust for your system. If you look inside the repo.sh script you can find at the end of the script following lines:

XML_REP="-sc tigase.db.xml.XMLRepository -su ../testsuite/user-repository.xml_200k_backup"
MYSQL_REP="-sc tigase.db.jdbc.JDBCRepository -su jdbc:mysql://localhost/tigase?user=root&password=mypass"
PGSQL_REP="-sc tigase.db.jdbc.JDBCRepository -su jdbc:postgresql://localhost/tigase?user=tigase"

java $D -cp $CP tigase.util.RepositoryUtils $MYSQL_REP $*

You can see that the source repository has been set to MySQL database with tigase as the database name, root the database user and mypass the user password.

You can adjust these settings for your system.

Now to import data to your repository simply execute the command:

./bin/repo.sh -import import-file.txt

Note, the import function is available from b895

The format of the import file is very simple. This is a flat file with comma separated values:
jid,password,roster_jid,roster_nick,subscriptio,group
To create such a file from MySQL database you have to execute command like this one:

SELECT a, b, c, d INTO OUTFILE 'import-file.txt' 
FIELDS TERMINATED BY ','
LINES TERMINATED BY '\n' 
FROM test_table;

Drupal authentication added

Well it is authentication against Drupal database at the moment. So it is not full integration with Drupal yet.

As Drupal keeps encrypted passwords in database the only possible authorization protocols are those based on PLAIN passwords.

To protect your passwords Tigase server must be used with SSL or TLS encryption.

Implementation of Drupal database based authorization is located in tigase.db.jdbc.DrupalAuth class. Although this class is capable of adding new user to the repository I recommend to switch in-band registration off due to the caching problems in Drupal. Changes in database are not synchronized with Drupal yet. Function for adding new users is implemented only to ease user accounts migration from different repository type from earlier Tigase server installation.

The idea of that implementation was to allow all accounts administration tasks from Drupal like: account creation, all accounts settings, like e-mail, full name, password changes and so on.

Tigase server uses following fields from Drupal database: name (user account name), pass (user account password), status (status of the account). Server picks up all changes instantly. If user status is not 1 then server won't allow user to login trough Jabber/XMPP even if user provides valid password.

There is no Roster management in Drupal yet. So Roster management have to be done from Jabber/XMPP client.

Two or more SessionManagers

In the most cases you use just one SessionManager object for your Tigase server installation. A single SM can handle multiple virtual domains with separate SSL certificates for each domain.

Sometimes, however you need very different configuration for each domain. For example you wish to use a separate database for a selected domain or you need a different set of plugins for each domain. For one domain you might want to allow user registration via XMPP and for another you might want to disable this feature. In such a case you need to load more than one session manager.

This is generally not a problem. You just need to add another component in the configuration and adjust default settings.

The question is now how Tigase server knows to which session manager it has to forward packets received from the network. Mind, there is only one component responsible for handling client connections. So it needs to know somehow which session manager is receiver for certain packet. Of course you set domain names in session manager too. But that is not enough. Tigase server supports cluster mode configuration where session manager can be running on a separate machine. So packet routings rules are not so simple to look at the domain name only. Therefore client connection manager (c2s) must know where is located the session manager responsible for handling the packet received from the network.

To solve the problem routings concept has been introduced. You can define packet routings based on the domain name set during XMPP stream initialization. Each time c2s component receives packet from the network it tries to resolve destination component for the packet based on the current routings table. If you look in you server XML configuration file and search for c2s configuration section you can find routings node. Default configuration for routings table is quite simple. Just a single regular expression:

   <node name="routings">
    <map>
     <entry key=".+" type="String" value="sess-man%40tigase.org"/>
     <entry key="multi-mode" type="Boolean" value="true"/>
    </map>
   </node>

As you can see this routings table forwards all packets to a single destination - session manager located on the tigase.org server.

Let's say we have now two session managers each of them is responsible for a separate domain.sm1@tigase.org handles requests for tigase.org and sm2@tigase.net handles requests for domain tigase.net. So let's modify our default configuration to properly spread the traffic between these two sessiona managers:

   <node name="routings">
    <map>
     <entry key="tigase.org" type="String" value="sm1%40tigase.org"/>
     <entry key="tigase.net" type="String" value="sm2%40tigase.net"/>
     <entry key="multi-mode" type="Boolean" value="true"/>
    </map>
   </node>

Please remember that a key is a regular expression in Java style: Pattern.html. You can match more than a single domain with the key, for example: tigase.+ to match all domains starting with tigase. The expression, however won't match domain: xmpp.tigase.org. To match this domain the expression would need to be: .+tigase.+.

Tigase and PyMSN-t transport

Any Jabber server and any transport connect with each other usually through external component protocol (XEP-0114). So all you need to do is to correctly prepare configuration for this protocol on both sides.

Continue reading to learn how to setup Tigase and PyMSN for working together...

There are a few basic parameters to set for this protocol:

• PORT number - this is standard thing for any TCP/IP connection. Usually the port number should be above 1024 and for PyMSN-t transport it is usually 5347.
• IP address - again, standard thing for any TCP/IP connection. If both applications - Jabber server and transport run on the same machine the IP address should be 127.0.0.1.
• SECRET - this is kind of connection password. Transport connects to the Jabber server and authenticates itself using this password. So no other, unauthorised transport can connect to the Jabber server. For our guide let the password be just secret.
• Transport ID - is an ID in Jabber network. Let's say we want to setup transport for MSN for the server tigase.org. Transport ID can be: msn.tigase.org. It could be also: anything.tigase.org but this name while still valid would be confusing for users and my suggestion is to avoid confusing names.
  Note! Transport ID should resolve to correct IP address. For your tests you can add the ID to /etc/hosts file.
  

Here is side by side configuration for both applications: PyMSN-t and Tigase to make them work together. I have setup both services on my laptop which hostname is test-d. To make sure both test-d and msn.test-d resolve to correct IP address I am adding entry to /etc/hosts file:

## In your case the IP address should be probably different. 
192.168.0.13    test-d            msn.test-d

Tigase server connects to MySQL database (or built-in XMLBD for simpler configuration variant).

I am not going to setup PyMSN-t to run in background as a system service. This is specific to the system you use and is covered in transport documentation and you operating system. Most of systems have own scripts to start services so I would recommend to use them. Here we just run it in foreground with full logging switched on to the console to make it easier track what happens.

<pymsnt>
  <!-- The JabberID of the transport -->
  <jid>msn.test-d</jid>
  <!-- The public IP or DNS name of the machine
    the transport is running on -->
  <host>test-d</host>
  <!-- The location of the PID file, relative
    to the PyMSNt directory -->
  <pid>/var/run/jabber/pymsn-t.pid</pid>
  <!-- If set, the transport will background
    itself when run, we don't want to do this right
    now. -->
  <!-- <background/> -->
  <!-- The IP address of the main Jabber server
    to connect to -->
  <mainServer>127.0.0.1</mainServer>
  <!-- The TCP port to connect to the Jabber
    server on (this is the default for Jabberd2) -->
  <port>5347</port>
  <!-- The authentication token to use when
    connecting to the Jabber server -->
  <secret>secret</secret>
  <lang>en</lang>
  <website>http://test-d/</website>
  <allowRegister/>
  <getAllAvatars/>
  <!-- Please give the port to listen for Jabber
    socks5 transfers on. Note the standard port number
    set here is 8010. This port
    however is in use on my machine so this is why 
    I had to set it to different value.-->
  <ftJabberPort>8014</ftJabberPort>
  <admins>
    <jid>tus@test-d</jid>
  </admins>
  <!-- The logging level
    0 -> No logging
    1 -> Log tracebacks
    2 -> Log tracebacks, warnings and errors
    3 -> Log everything -->
  <debugLevel>3</debugLevel>
  <!-- The file to log to. Leave this disabled
    for stdout -->
  <!-- <debugFile>debug.log</debugFile> -->
</pymsnt>

ENC="-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8"
DRV="-Djdbc.drivers=com.mysql.jdbc.Driver"
CLASSPATH="${CLASSPATH}:libs/jdbc-mysql.jar"
JAVA_OPTIONS="${ENC} ${DRV} -server -Xms100M -Xmx100M "
TIGASE_CONFIG="etc/tigase-mysql.xml"
## All TIGASE_OPTIONS settings must be in single line
## They are split to make them more readable
TIGASE_OPTIONS="--gen-config-all --admins \"tus@test-d\"
 --virt-hosts test-d,localhost --debug server
 --ext-comp \"test-d,msn.test-d,5347,secret,plain,accept\"
 --user-db mysql --user-db-uri
 \"jdbc:mysql://localhost/tigase?user=tigase&password=mypass\" "

python /usr/lib/python2.4/site-packages/pymsn-t/pymsn-t.py -c /etc/jabber/pymsn-t.xml

./bin/tigase.sh start etc/tigase.conf

[2007-05-07 13:00:39] Starting factory <twisted.xish.xmlstream.XmlStreamFactory instance at 0xb7ce80ac>
[2007-05-07 13:00:39] <twisted.internet.tcp.Connector instance at 0xb7ceb24c> will retry in 2 seconds
[2007-05-07 13:00:39] Stopping factory <twisted.xish.xmlstream.XmlStreamFactory instance at 0xb7ce80ac>
[2007-05-07 13:00:41] Starting factory <twisted.xish.xmlstream.XmlStreamFactory instance at 0xb7ce80ac>
[2007-05-07 13:00:41] <twisted.internet.tcp.Connector instance at 0xb7ceb24c> will retry in 5 seconds
[2007-05-07 13:00:41] Stopping factory <twisted.xish.xmlstream.XmlStreamFactory instance at 0xb7ce80ac>
[2007-05-07 13:00:46] Starting factory <twisted.xish.xmlstream.XmlStreamFactory instance at 0xb7ce80ac>
[2007-05-07 13:00:46] <twisted.internet.tcp.Connector instance at 0xb7ceb24c> will retry in 15 seconds
[2007-05-07 13:00:46] Stopping factory <twisted.xish.xmlstream.XmlStreamFactory instance at 0xb7ce80ac>

[2007-05-07 13:29:04] Starting factory <twisted.xish.xmlstream.XmlStreamFactory instance at 0xb7cf00ac>
[2007-05-07 13:29:04] INFO ::  ::  :: componentConnected :: PyTransport :: {'xmlstream': <twisted.xish.xmlstream.XmlStream instance at 0xb7d0feac>, 'self': 'instance'}

tail -f logs/tigase-console.log

2007-05-07 12:29:05  ComponentConnectionManager.processHandshake() FINE: Connected to: msn.test-d
2007-05-07 12:29:05  ComponentConnectionManager.updateServiceDiscovery() FINEST: Modifing service-discovery info: <item name="XEP-0114 connected" jid="msn.test-d"/>

Note! There was a bug in jabber:iq:register plugin which caused problems with registering account in transport. Please use build 432 or later.

StanzaSender

This is a component which make it easier to integrate Jabber/XMPP server with other, third-party tools.

It simply allows you to send stanzas from your application without implementing any Jabber/XMPP specific code. The component regularly reads specified data source for XMPP packets to send. The data source can be an SQL database, directory on your filesystem or anything you might want.

If you have Web application for example which you want to send notifications of any event to selected users you can install StanzaSender component on your Tigase server. It will help you to easily distribute your messages to end-users.

How it works

The module itself doesn't do anything. It just schedules tasks and sends stanzas which come from... it doesn't know. To do actual work of retrieving stanzas from data source the component uses tasks.

In theory the task can retrieve XMPP packets for sending from any location or may just generate stanzas on its own.

In practise there are 2 tasks already implemented and ready to use. You can treat them as a sample code for implementation of your own tasks customised for your specific needs or you can just use these tasks as they are.

The tasks which are available are:

• FileTask retrieving stanzas from directory in file system.
• JDBCTask retrieving stanzas from SQL database.

FileTask

FileTask implements tasks for cyclic retrieving stanzas from a directory and sending them to the StanzaHandler object.

It looks for any new stanza to send. Any single file can contain only single stanza to send and any entry in database table can also contain only single stanza to send. File on hard disk and record in database is deleted after it is read.

Any file in given directory is treated the same way - Tigase assumes it contains valid XML data with XMPP stanza to send. You can however set in configuration, using wildchars which files contain stanzas. All stanzas must contain complete data including correct "from" and "to" attributes.

By default it looks for *.stanza files in /var/spool/jabber/ folder but you can specify different directory name in initialization string. Sample initialization strings:
/var/spool/jabber/*.stanza
/var/spool/jabber/*
The last is equal to:
/var/spool/jabber/
Note the last forward slash '/' is required in such case if the last element of the path is a directory.

Please note! Tigase must have writing permissions for this directory, otherwise it may not function properly.

JDBCTask

JDBCTask implements tasks for cyclic retrieving stanzas from database and sending them to the StanzaHandler object.

Database table format:

• id - numerical unique record indetifier.
• stanza - text field containing valid XML data with XMPP stanza to send.

Any record in this table is treated the same way - Tigase assmes it contains valid XML data with XMPP stanza to send. No other data are allowed in this table. All stanzas must be complete including correct "from" and "to" attriutes.

By default it looks for stanzas in xmpp_stanza table but you can specify different table name in connection string. Sample connection string:
jdbc:mysql://localhost/tigasedb?user=tigase&
password=pass&table=xmpp_stanza

Please note the last parameter which is specific to JDBCTask. You can specify the table name which stores stanzas for sending. If omitted default value is: xmpp_stanza.

Configuration

It is Tigase component so the configuration is similar to configuration of all other components. The simplest way to get the settings for StanzaSender is by generating configuration with all possible components. To do this you have to run Tigase server with --gen-config-all parameter set.

By default this component name is ssend and here is a content of the configuration file for StanzaSender:

It is one of msg-receivers:

<entry type="String[]" key="id-names">
  ...
  <item value="ssend"/>
</entry>

To activate the component and specify class name for it following entries has been added:

<entry value="true" type="Boolean" key="ssend.active"/>
<entry value="tigase.server.ssender.StanzaSender" type="String" key="ssend.class"/>

And the main settings section for the component:

<component name="ssend">
  <map>
   <entry value="10" type="Long" key="default-interval"/>
   <entry value="1000" type="Integer" key="max-queue-size"/>
   <entry type="String[]" key="stanza-listeners">
    <item value="jdbc"/>
    <item value="file"/>
   </entry>
  </map>
  <node name="file">
   <map>
    <entry value="true" type="Boolean" key="active"/>
    <entry value="tigase.server.ssender.FileTask" type="String" key="class-name"/>
    <entry value="%2Fvar%2Fspool%2Fjabber%2F*.stanza" type="String" key="init-string"/>
    <entry value="10" type="Long" key="interval"/>
   </map>
  </node>
  <node name="jdbc">
   <map>
    <entry value="true" type="Boolean" key="active"/>
    <entry value="tigase.server.ssender.JDBCTask" type="String" key="class-name"/>
    <entry value="jdbc%3Amysql%3A%2F%2Flocalhost%2Ftigase%3Fuser%3Dtigase%26password%3Dmypass%26table%3Dxmpp_stanza" type="String" key="init-string"/>
    <entry value="10" type="Long" key="interval"/>
   </map>
  </node>
 </component>

I think most of parameters should be pretty clear but some may need a little explanation. General StanzaSender parameters:

• default-interval number which specifies in seconds how often should the task look in data source for new packets to send.
• max-queue-size is a number which specifies internal packets queue size. This is used to prevent the component from consume all the memory for data in case the component can not process them.
• stanza-listeners is a list of task names to load. Each task can read XMPP packets to send from different data source. You can load as many listeners (tasks) as you need. Each task must read stanzas from different data source.

Each task has own, separate parameters list. For each task from the stanza-listeners list there is a separate section with parameters for each task:

• active boolean switch allowing you to turn on/off the task without removing configuration completely.
• class-name Java class name which implements the task. This class must extend tigase.server.ssender.SenderTask and it is loaded at runtime.
• init-string is kind of data source connection string. For database it is just database connection string, for file system this is just a directory name. It may be even different for different tasks. The 2 tasks already implemented have some specific features: FileTask allows you to use wild-chars in directory/ file name specification and JDBCTask allows you to specify additional parameter at the end of JDBC connection string - database table name. For specific examples look at above config sections.
• interval is a number which allows you to specify different interval in seconds for checking data source for each task.

Server certificates

Documents describing how to obtain and manage server certificates.

keytool -genkey -alias yourdomain -keystore rsa-keystore \
    -keyalg RSA -sigalg MD5withRSA

Enter keystore password: 123456

What is your first and last name?
  [Unknown]: jabber.myserver.org
What is the name of your organizational unit?
  [Unknown]:
What is the name of your organization?
  [Unknown]:
What is the name of your City or Locality?
  [Unknown]:
What is the name of your State or Province?
  [Unknown]:
What is the two-letter country code for this unit?
  [Unknown]:
Is CN=jabber.myserver.org, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct?
  [no]: yes

Enter key password for <mykey>
             (RETURN if same as keystore password):

keytool -certreq -alias yourdomain -keystore rsa-keystore

-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBrzCCARgCAQAwbzEQMA4GA1UEBhMHVW5rbm93bjEQMA4GA1UECBMHVW5rbm93bjEQMA4GA1UE
BxMHVW5rbm93bjEQMA4GA1UEChMHVW5rbm93bjEQMA4GA1UECxMHVW5rbm93bjETMBEGA1UEAxMK
c2VydmVyLm9yZzCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAs73Y70725OcG0j4kpCfDX59e
qhz2gdGOO0LyMO7rm4m+ZCenq8E88M0RJ8/LV/7q0mtOAzbI8dtXZnmJ74xihCH8ZTFpVDMyFWgk
WCj2kz+IUD9vWt6i1UepSkr1a/jYmVMN3RSaoS+j+QLBsJ4rWeOHgIdbiF5tnMhoZMXU//0CAwEA
AaAAMA0GCSqGSIb3DQEBBAUAA4GBAHY5r9rftqiKESbbkCcfVhvnUqN4aMTC8/zXWwzBX8guC0kd
H46+p6eizwJg6p+h6rqShG2OqXCPrJzO3buHr1jEWRTlB8l5CM53L/xq61nYuaSf5R7Vv/RX2+aD
JyoBqYIoSUED0+Sjhej0SUPTOdpA/bfnqdfdtckday4vsLPC
-----END NEW CERTIFICATE REQUEST-----

-----BEGIN CERTIFICATE-----
MIICUDCCAbkCBEUqAK0wDQYJKoZIhvcNAQEEBQAwbzEQMA4GA1UEBhMHVW5rbm93bjEQMA4GA1UE
CBMHVW5rbm93bjEQMA4GA1UEBxMHVW5rbm93bjEQMA4GA1UEChMHVW5rbm93bjEQMA4GA1UECxMH
VW5rbm93bjETMBEGA1UEAxMKc2VydmVyLm9yZzAeFw0wNjEwMDkwNzU2MjlaFw0wNzAxMDcwNzU2
MjlaMG8xEDAOBgNVBAYTB1Vua25vd24xEDAOBgNVBAgTB1Vua25vd24xEDAOBgNVBAcTB1Vua25v
d24xEDAOBgNVBAoTB1Vua25vd24xEDAOBgNVBAsTB1Vua25vd24xEzARBgNVBAMTCnNlcnZlci5v
cmcwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBALO92O9O9uTnBtI+JKQnw1+fXqoc9oHRjjtC
8jDu65uJvmQnp6vBPPDNESfPy1f+6tJrTgM2yPHbV2Z5ie+MYoQh/GUxaVQzMhVoJFgo9pM/iFA/
b1reotVHqUpK9Wv42JlTDd0UmqEvo/kCwbCeK1njh4CHW4hebZzIaGTF1P/9AgMBAAEwDQYJKoZI
hvcNAQEEBQADgYEAQqRPdkbc/pdDcPIWOThn2XPp0gitPkXq89ZM1mb0Pib1OISj9ekjqhEZz0UA
cI6g1XttpY6hKi6Gg+mRbwiHNVebkDLamE2UIcVJ1wBtowYeOcV1CcLnlj91ScMKNhfD5ebQL+be
tWWrJX3ep+80kF/NdVkc7htGOhLebopp8SQ=
-----END CERTIFICATE-----

keytool -import -keystore rsa-keystore -file root.crt \
    -alias root

keytool -import -alias yourdomain -keystore rsa-keystore \
    -file your-certificate.cer

keytool -import -keystore rsa-keystore -file rootCA.cer

openssl pkcs12 -export -inkey ssl.key -in ssl.crt \
    -out mycert.pfx -name "default"

keytool -importkeystore -srckeystore mycert.pfx \
    -srcstoretype pkcs12 -destkeystore rsa-keystore \
    -srcalias default -destalias yourdomain \
    -destkeypass your_keystore_pass

openssl x509 -req -days 365 -in yourdomain.com.csr -signkey yourdomain.com.key -out yourdomain.com.crt

cat yourdomain.com.crt yourdomain.com.key > yourdomain.com.pem

cat yourdomain.com.crt yourdomain.com.key sub.class1.xmpp.ca.crt ca.crt > yourdomain.com.pem

-----BEGIN CERTIFICATE-----
MIIG/TCCBeWgAwIBAgIDAOwZMA0GCSqGSIb3DQEBBQUAMIGMMQswCQYDVQQGEwJJ
.
.
.
pSLqw/PmSLSmUNIr8yQnhy4=
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
WW91J3JlIGtpZGRpbmchISEKSSBkb24ndCBzaG93IHlvdSBvdXIgcHJpdmF0ZSBr
.
.
.
ZXkhISEhCkNyZWF0ZSB5b3VyIG93biA7KSA7KSA7KQo=
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIIHyTCCBbGgAwIBAgIBATANBgkqhkiG9w0BAQUFADB9MQswCQYDVQQGEwJJTDEW
.
.
.
xV/stleh
-----END CERTIFICATE-----

--ssl-container-class=tigase.extras.io.PEMSSLContextContainer

openssl s_client -connect tigase.org:5223 -CApath /etc/ssl/certs

verify return:1verify return:1

verify return:0

verify error:num=19:self signed certificate in certificate chain

Server configuration 5.x

Collection of documents and guides for the Tigase server version 5.x and later.

create table tigase_configuration (
-- The component name by which the configuration parameter
-- is used.
  component_name varchar(127) NOT NULL,

-- The configuration property key name or identifier.
  key_name varchar(127) NOT NULL,

-- The configuration property value
  value varchar(8191) NOT NULL,

-- The cluster node by which the configuration property is read,
-- if empty it will be read by all cluster nodes.
  cluster_node varchar(255) NOT NULL DEFAULT '',

-- Additional, secondary identifier for the configuration property.
-- The configuration can be organised in a hierarchical way to allow
-- multiple occurrences of the same property name for a single
-- component, for example you can have the same property for 
-- different tcp/ip ports set to a different value:
-- c2s/5222/port_type=plain
-- c2s/5223/port_type=ssl
-- the port number is a secondary identifier.
  key_node varchar(127) NOT NULL DEFAULT '',

--  Not currently used. In future it will be used to distinguish between
-- different kind of properties (initial settings, defaults, updated by 
-- user, etc...)
  flag varchar(32) NOT NULL DEFAULT 'DEFAULT',

-- The system detects basic Java types and stores information about
-- the property type, when the property is read the original property
-- type is restored and provided to the component without need for
-- a parsing or conversion.
  value_type varchar(8) NOT NULL DEFAULT 'S',

-- It is not currently used. In the future it will be used to reload 
-- settings changed in last, defined period of time. Basicall, the
-- system can automatically check the configuration database to 
-- see whether some properties have been updated, then reload
-- them and apply automatically.
  last_update           timestamp,

primary key(cluster_node, component_name, key_node, 
                  key_node, flag));

-Dtigase-configurator=tigase.conf.Configurator

Configuration

This section contains some specific description for non-standard Tigase installations.

--auth-db = tigase-custom
--auth-db-uri = jdbc:mysql://localhost/drupal?user=user&password=passwd

basic-conf/auth-repo-params/conn-valid-query=select 1
basic-conf/auth-repo-params/init-db-query=update tig_users set online_status = 0
basic-conf/auth-repo-params/add-user-query={ call TigAddUserPlainPw(?, ?) }
basic-conf/auth-repo-params/del-user-query={ call TigRemoveUser(?) }
basic-conf/auth-repo-params/get-password-query=select user_pw from tig_users where user_id = ?
basic-conf/auth-repo-params/update-password-query=update tig_users set user_pw = ? where user_id = ?
basic-conf/auth-repo-params/user-logout-query=update tig_users, set online_status = online_status - 1 where user_id = ?
basic-conf/auth-repo-params/non-sasl-mechs=password,digest
basic-conf/auth-repo-params/sasl-mechs=PLAIN,DIGEST-MD5

add-user-query={ call TigAddUserPlainPw(?, ?) }

add-user-query=insert into users (user_id, password) values (?, ?)

--comp-name-1=pubsub
--comp-class-1=tigase.pubsub.PubSubComponent

--comp-name-2=pubsub-priv
--comp-class-2=tigase.pubsub.PubSubComponent

--comp-name-2=muc
--comp-class-2=tigase.muc.MUCComponent

--auth-db-uri = jdbc:mysql://localhost/drupal?user=user&password=passwd

--auth-db = tigase-auth

--auth-db = tigase.db.jdbc.TigaseAuth

--auth-db = drupal

--auth-db = tigase-custom

--user-db-uri=jdbc:mysql://localhost/tigasedb?user=nobody&password=pass&autoCreateUser=true

External component configuration

In the Tigase server version 4.4.x a new implementation for connecting external components has been introduced.

It is much simpler to setup and follows the same configuration standards as all other components. It is also much more powerful as a single instance can control many TCP/IP ports and many external components on each port and even allows for multiple connections for the same component. It supports both XEP-0114 and XEP-0225 with protocol auto-detection mechanisms. Protocols are pluggable so in future more protocols can be supported or custom extensions to existing protocols can be added.

The implementation also supports scripting API and new domains with passwords can be added at run-time using ad-hoc commands. New scripts can be loaded to even further control all connected external components.

Even though it is much simpler to setup and to use it also offers a lot of new functionality and features. Pages in this guide describe in details all the administration aspects of setting up and managing external components.

--comp-name-1 = ext
--comp-class-1 = tigase.server.ext.ComponentProtocol

--comp-name-1 = ext
--comp-class-1 = tigase.server.ext.ComponentProtocol
--external = muc.devel.tigase.org:muc-secret:listen:5270

--comp-name-1 = ext
--comp-class-1 = tigase.server.ext.ComponentProtocol
--external = muc.devel.tigase.org:muc-secret:listen:5270, \
    pubsub.devel.tigase.org:pubsub_pass, \
    msn.devel.tigase.org:msn_pass

--comp-name-1 = ext
--comp-class-1 = tigase.server.ext.ComponentProtocol
--external = muc.devel.tigase.org:muc-secret:listen:5270, \
   pubsub.devel.tigase.org:pubsub_pass:listen:5271, \
   msn.devel.tigase.org:msn_pass:listen:5272

--comp-name-1 = ext
--comp-class-1 = tigase.server.ext.ComponentProtocol
--external = devel.tigase.org:muc-secret:connect:5270:muc.devel.tigase.org

--comp-name-1 = ext
--comp-class-1 = tigase.server.ext.ComponentProtocol
--external = devel.tigase.org:mucsecret:connect:5270:muc.devel.tigase.org, \
  devel.tigase.org:pubsub_pass:connect:5271:pubsub.devel.tigase.org, \
  devel.tigase.org:msn_pass:connect:5272:msn.devel.tigase.org

--comp-name-1 = ext
--comp-class-1 = tigase.server.ext.ComponentProtocol
--external = devel.tigase.org:mucsecret:connect:5270:muc.devel.tigase.org:accept, \
  devel.tigase.org:pubsub_pass:connect:5270:pubsub.devel.tigase.org:client

config-type = --gen-config-comp
--debug = server
--user-db = derby
--admins = admin@devel.tigase.org
--user-db-uri = jdbc:derby:/tigasedb
--virt-hosts = devel.tigase.org
--comp-name-1 = muc
--comp-class-1 = tigase.muc.MUCComponent
--external = muc.devel.tigase.org:muc-pass:connect:5270:devel.tigase.org:accept

--comp-name-1 = ext
--comp-class-1 = tigase.server.ext.ComponentProtocol

config-type = --gen-config-comp
--debug = server
--user-db = derby
--admins = admin@devel.tigase.org
--user-db-uri = jdbc:derby:/tigasedb
--virt-hosts = devel.tigase.org
--comp-name-1 = muc
--comp-class-1 = tigase.muc.MUCComponent
--comp-name-2 = pubsub
--comp-class-2 = tigase.pubsub.PubSubComponent
--external = muc.devel.tigase.org:muc-pass:connect:5270:devel.tigase.org:accept, \
  pubsub.devel.tigase.org:pubsub-pass:connect:5270:devel.tigase.org:accept

config-type = --gen-config-comp
--debug = server
--user-db = derby
--admins = admin@devel.tigase.org
--user-db-uri = jdbc:derby:/tigasedb
--virt-hosts = devel.tigase.org
--comp-name-1 = muc
--comp-class-1 = tigase.muc.MUCComponent
--comp-name-2 = pubsub
--comp-class-2 = tigase.pubsub.PubSubComponent
--external = muc.devel.tigase.org:muc-pass:connect:5270:devel.tigase.org:client
--bind-ext-hostnames=pubsub.devel.tigase.org

MySQL database schema upgrade for Tigase 4.0

For number of reasons the database schema had to be changed for Tigase server version 4.0. The most important are:

• Compliance with the XMPP RFC which says that each part of JID may have up to 1023 characters. We store in the database user JIDs without resource name thus the maximum possible size of the user id is 2047. There aren't really JIDs that long yet but we experienced quite long JIDs in a few installations already so we decided to prepare Tigase to accept any JID allowed by RFC.
• Performance and flexibility - the Tigase server now accesses database using stored procedures. This allows for any database storage format and it doesn't really matter for the Tigase server what is the database schema how data is organized inside. What it needs is just bunch of stored procedures to access the data. This allows for much more flexibility in storing user data as well as much easier integration with third-party systems and also organize data in more efficient way.

Therefore when you run the Tigase server now it may (depending on what exact SVN revision you use) refuse to start if it detects that the database schema is not updated. If it happens just follow steps below to update the database schema and start the server again. Updating of the database schema is very easy and almost fully automated process. Just follow the steps below and you should be able to run new version of the Tigase server in a few minutes or even seconds depending on your database size. It takes around 7 minutes to update database with 200k user accounts on an average machine. Note. Do not update the database schema before the Tigase server tells you to do so. And do a database backup before starting the schema update.

Please note. I have done a few schema upgrades already in a different configurations and here are a few tips which might be useful if something goes wrong:

1. You really, really have to do the DB backup (database dump) before upgrading. If you don't you might not be able to revert database on your own. Contact me in case of problems.
2. In case of error: ERROR 1419 (HY000) at line 31 in file: 'database/mysql-schema-4-sp.schema': You do not have the SUPER privilege and binary logging is enabled (you *might* want to use the less safe log_bin_trust_function_creators variable) Restore the database following description found below and run the update again as MySQL super user.
3. The following error may manifest itself in many ways from the NullPointerException in the Tigase server log file to message like this: User does not have access to metadata required to determine stored procedure parameter types. If rights can not be granted, configure connection with "noAccessToProcedureBodies=true" to have driver generate parameters that represent INOUT strings irregardless of actual parameter types. The best solution to this is to grant proper permissions to this user. Enter the MySQL command line mode as MySQL super user:
   

    $ mysql -u root -proot_passwd mysql
   mysql> GRANT SELECT, INSERT, UPDATE ON \`mysql\`.\`proc\` TO 'tigase_user'@'localhost';
   mysql> GRANT SELECT, INSERT, UPDATE ON \`mysql\`.\`proc\` TO 'tigase_user'@'%';
   mysql> GRANT SELECT, INSERT, UPDATE ON \`mysql\`.\`proc\` TO 'tigase_user';
   mysql> FLUSH PRIVILEGES;
    $
   

1. tigasedb is a database name
2. tigase_user is a database user name
3. mypass is database user password

First things first - make a database backup:

mysqldump -u tigase_user -pmypass tigasedb > tigasedb_dump.sql

If you need to restore database for any reason execute following commands:

msyqladmin -u tigase_user -pmypass drop tigasedb
mysqladmin -u tigase_user -pmypass create tigasedb
mysql -u tigase_user -pmypass tigasedb < tigasedb_dump.sql

Note! You may be required to use root user and his password to execute mysqladmin commands. Ok we have the database backup and we know how to restore it. Now we can run schema upgrade script:

mysql -u tigase_user -pmypass tigasedb < database/mysql-schema-upgrade-to-4.sql

The script should generate output like this:

Droping index for user_id column
Resizing user_id column to 2049 characters to comply with RFC
Creating a new index for user_id column for first 765 bytes of the field
Adding sha1_user_id column
Adding user_pw column
Adding last_login column
Adding last_logout column
Adding online_status column
Adding failed_logins column
Adding account_status column
Creating a new index for user_pw column
Creating a new index for last_login column
Creating a new index for last_logout column
Creating a new index for account_status column
Creating a new index for online_status column
Resizing node column to 255 characters
Changing pval column type to mediumtext
Loading stored procedures definitions
Setting passwords encoding in the database
Converting database to a new format
Creating a new index for sha1_user_id column
Setting schema version to 4.0
All done, database ready to use!

Packets filtering

Tigase offers different ways to filter XMPP packets flying through the server. The most common case to use packet filtering is to restrict users from sending or receiving packets based on the sender or received address.

There are also possible different scenarios: time based filtering, content filtering, volume filtering and so on.

All pages in this section describe different filtering strategies.

repo.getData(user_id, null, DomainFilter.ALLOWED_DOMAINS_KEY, null)

Virtual Hosts in the Tigase server

The Tigase server supports multiple virtual hosts for a single server installation. This is supported via VHostManager - the new Tigase server component added recently to the implementation. Virtual hosts can be added or removed, enabled or disabled at the server runtime without restarting the service or disrupting normal operation.

This document describes how virtual hosts work in the Tigase server and how to take the most of this feature in your installation.

The simplest and default way to set virtual hosts is the server configuration. You can either edit manually the init.properties file or use the graphical installer/configuration program to set the property. If you want to edit it manually search for '--virt-hosts' property for more detailed description.

Alternatively you can use the GUI installer as shown on the left hand side to set a list of virtual hosts.

This method however has many disadvantages. It requires the server restart after each change, the configuration file is not the best place to store long list of virtual domains and you can not actually set any additional parameters for the domain other than it does exist or not.

There is another way to store and control virtual domains in the Tigase server. They can be put in the database and managed using ad-hoc commands. List of domains can be modified outside the Tigase server through any third-party system or web application and the server reloads the list of when received VHOSTS_RELOAD ad-hoc command.

There are 2 more ad-hoc commands which allow you to add/update and remove virtual hosts via XMPP protocol:

• VHOSTS_UPDATE - for adding new virtual host or changing parameters of the existing domain
• VHOSTS_REMOVE - for removing existing virtual domain from the list of the server domains.

By default, both commands cause vhosts list update in the permanent repository. This is however VHostRepository implementation dependent feature and can be changed in your repository implementation.

Commands for virtual domains management can be executed using any XMPP client with a good support for service discovery and ad-hoc commands, for example Psi. Commands are accepted only when they are sent by the service administrator.

Please refer to documents listed below for more detailed information on the following topics:

• Managing virtual domains using Psi client.
• Specification for ad-hoc commands used to manage virtual domains.
• API description for virtual domains management in the Tigase server.

<iq type="set" 
    to="vhost-man@existing.domain.com"
    id="aac8a">
  <command xmlns="http://jabber.org/protocol/commands"
           node="VHOSTS_RELOAD" />
</iq>

<iq from="vhost-man@existing.domain.com"
    type="result" 
    to="cmd-sender-admin@existing.domain.com" 
    id="aac8a">
  <command xmlns="http://jabber.org/protocol/commands"
           status="completed"
           node="VHOSTS_RELOAD">
    <x xmlns="jabber:x:data" type="result">
      <field type="fixed" var="Note">
        <value>Current number of VHosts: 123</value>
      </field>
    </x>
  </command>
</iq>

<iq from="vhost-man@existing.domain.com"
    type="error"
    to="cmd-sender-admin@existing.domain.com"
    id="aac8a">
  <command xmlns="http://jabber.org/protocol/commands"
           node="VHOSTS_RELOAD" />
  <error type="auth" code="401">
    <not-authorized xmlns="urn:ietf:params:xml:ns:xmpp-stanzas" />
    <text xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"
          xml:lang="en">
      You are not authorized for this action.
    </text>
  </error>
</iq>

<iq type="set"
    to="vhost-man@existing.domain.com"
    id="aacba">
  <command xmlns="http://jabber.org/protocol/commands"
           node="VHOSTS_UPDATE">
    <x xmlns="jabber:x:data" type="submit">
      <field type="text-single" 
             var="VHost">
        <value>new-virt.domain.com</value>
      </field>
      <field type="list-single"
             var="Enabled">
        <value>true</value>
      </field>
    </x>
  </command>
</iq>

<iq from="vhost-man@existing.domain.com"
    type="result"
    to="cmd-sender-admin@existing.domain.com"
    id="aacba">
  <command xmlns="http://jabber.org/protocol/commands"
           status="completed"
           node="VHOSTS_UPDATE">
    <x xmlns="jabber:x:data" type="result">
      <field type="fixed" var="Note">
        <value>Current number of VHosts: 124</value>
      </field>
    </x>
  </command>
</iq>

<iq type="set"
    to="vhost-man@existing.domain.com"
    id="aacba">
  <command xmlns="http://jabber.org/protocol/commands"
           node="VHOSTS_REMOVE">
    <x xmlns="jabber:x:data" type="submit">
      <field type="text-single"
             var="VHost">
        <value>virt-nn.domain.com</value>
      </field>
    </x>
  </command>
</iq>

<iq from="vhost-man@existing.domain.com"
    type="result"
    to="cmd-sender-admin@existing.domain.com"
    id="aacba">
  <command xmlns="http://jabber.org/protocol/commands"
           status="completed"
           node="VHOSTS_REMOVE">
    <x xmlns="jabber:x:data" type="result">
      <field type="fixed" var="Note">
        <value>Current number of VHosts: 124</value>
      </field>
    </x>
  </command>
</iq>

Virtual components for the cluster mode

Let's assume you have a cluster installation and you want to include a component in  your installation which doesn't support the cluster mode yet. If you put it on all nodes as a separate instances they will work out of sync and overall functionality might be useless. If you put on one node only it will work correctly but it will be visible to users connected to this one node only.

Ideally you would like to have a mechanism to install it on one node and put some redirections on other nodes to forward all packets for this component to a node where this component is working. Redirection on it's own is not enough however because the component must be visible in service discovery list and must be visible somehow to users connected to all nodes.

This is where the virtual components are handy. They are visible to users as a local normal component, they seem to be a real local component but in fact they just forward all requests/packets to a cluster node where the real component is working.

Virtual component is a very lightweight ServerComponent implementation in the Tigase server. It can pretend to be any kind of component and can redirect all packets to a given address. They can mimic native Tigase components as well as third-party components connected over external component protocol (XEP-0114).

Configuration is very simple and straightforward. In fact it is very similar to configuration of any Tigase component. You set a real component name as a name of the component and a vritual component class name to load. Let's say we want to deploy MUC component this way. The MUC component is visible as muc.domain.our in the installation. Thus the name of the component is: muc

--comp-name-1=muc
--comp-class-1=tigase.cluster.VirtualComponent

This is pretty much all you need to load a virtual component. A few other options are needed to point to correct destination addresses for packets forwarding and to set correct service discovery parameters:

muc/redirect-to=muc@cluster-node-with-real-muc.domain.our
muc/disco-name=Multi User Chat
muc/disco-node=
muc/disco-type=text
muc/disco-category=conference
muc/disco-features=http://jabber.org/protocol/muc

That's it.

Configuration

This section contains the Tigase server configuration manuals and guides.

java -Djdbc.drivers=org.postgresql.Driver
 -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8
 -server -Xms100M -Xmx100M 
 -cp "libs/pg73jdbc3.jar;jars/tigase-server.jar;libs/tigase-xmltools.jar;libs/tigase-utils.jar"
 tigase.server.XMPPServer
 -c "etc/tigase.xml" 
 --gen-config-def --user-db pgsql
 --user-db-uri "jdbc:postgresql://localhost/tigase?user=tigase"

./bin/tigase.sh run tigase.conf

Connecting the Tigase server to MySQL database

Please before continuing reading of this manual have a look at the initial MySQL database setup. It will help you with database preparation for connecting the Tigase server.

The easiest way to setup the Tigase server for connecting with MySQL database is to use so called configuration wizards (configuration generators) which release you from manually editing the XML configuration file and allow you quickly regenerate the XML configuration file in case of problems.

The article above describes the older way for using configuration generators which is a bit more difficult and doesn't work on Windows system. The guide below describes a new way to use them which is simpler and can be applied for Windows systems as well. It is using init.properties file where you can put all your initial configuration parameters.

This guide describes MySQL database connection parameters.

Well the guide is actually very short as there are example configuration files which can be used and customized for your environment.

Unfortunately these files are not included yet in the server version 3.x binary release and you have to download them from the SVN repository using following links:

1. tigase-mysql.conf - the Tigase server startup file. The only difference from the default one is that it points to the file described below to load initial parameters.
2. init-mysql.properties - the file contains a few initial parameters which can/should be adjusted to your environment. Here is a content of the file with each line described:
   

   # Load standard set of the server components.
   # Look at the http://www.tigase.org/configuration-wizards
   # document for other possible values. Normally you don't
   # need to change this line.
   config-type=--gen-config-def
   # List of administrator accounts, please replace them with
   # administrator accounts in your installation
   --admins=admin@tigase.org,admin@test-d
   # The line says that the database used by the Tigase server is 'mysql'
   # Look at the configuration wizards article for different options
   # You can also put here a Java class name if you have a custom
   # implementation for a database connector.
   --user-db=mysql
   # The line contains the database connection string. This is database
   # specific string and for each kind of database it may look differently.
   # Below string is for MySQL database. Please modify it for your system.
   # MySQL connector requires connection string in the following format:
   # jdbc:mysql://[hostname]/[database name]?user=[user name]&password=[user password]
   --user-db-uri=jdbc:mysql://localhost/tigasedb?user=tigase_user&password=mypass
   # Virtual domains for your server installation, comma separated list of vhosts
   --virt-hosts=tigase.org,test-d,localhost
   # Select what packages you want to have logging switched for
   # The below setting is recommended for the initail setup and it is required
   # when asking for help with setting the server up
   --debug=server
   

Download both files and put them to your etc/ directory.

Edit the init-mysql.properties for your environment.

Remove the XML configuration file.

Start the server using following command:

./bin/tigase.sh start etc/tigase-mysql.conf

Ask more questions if you got stuck or need any help with this.

Integrating Tigase server with Drupal

Tigase supports integration with Drupal on many levels. At the moment all stuff described below work with Drupal version 4.x and 5.x. They may also work with Drupal 6.x but this version hasn't been tested.

First of all it can authenticate users against Drupal database which means you have the same user account for both Drupal website and XMPP (Jabber) server. More over in such a configuration all account management is done via Drupal web interface like account creation, password change update user details and so on. Administrator can temporarily disable user account and this is respected by the Tigase server too.

Connecting to Drupal database

The best way to setup Tigase with Drupal database is via configuration wizards that is init.properties file where you can put initial setting for Tigase configuration.

If you look in etc/ directory of your Tigase installation you should find a few files there. The one we want to base our configuration on is: init-mysql.properties. In some older packages the file might be missing, then you can download it from the SVN repository.

If you look inside the file and strip all the comments you would see following lines:

config-type=--gen-config-def
--admins=admin@tigase.org,admin@tigase.net
--user-db=mysql
--user-db-uri=jdbc:mysql://localhost/tigasedb?user=tigase_user&password=mypass
--virt-hosts=tigase.org,tigase.net
--debug=server

All you need to connect to Drupal database are 2 following lines:

--auth-db=drupal
--auth-db-uri=jdbc:mysql://localhost/drupal?user=drupalusr&password=drupalpass

Let's combine it in a single file called etc/init-drupal.properties:

config-type=--gen-config-def
--admins=admin@tigase.org,admin@tigase.net
--auth-db=drupal
--auth-db-uri=jdbc:mysql://localhost/drupal?user=drupalusr&password=drupalpass
--user-db=mysql
--user-db-uri=jdbc:mysql://localhost/tigasedb?user=tigase_user&password=mypass
--virt-hosts=tigase.org,tigase.net
--debug=server

In theory you can load Tigase database schema to Drupal database and then both db-uris would have the same database connection string. More details about setting up and connecting to MySQL database can be found in the guide.

You need also to edit etc/tigase.conf file to point to your newly created properties file. The last line which looks like this:

TIGASE_OPTIONS=" --property-file etc/init.properties "

should be changed to following:

TIGASE_OPTIONS=" --property-file etc/init-drupal.properties "

Make sure you have Java-6 installed and JAVA_HOME is set to correct location. If JAVA_HOME is not set you can add following line to etc/tigase.conf file:

JAVA_HOME="/your/java-6-location"

The best way to check whether the variable is set correctly is with command:

 $ ls -l $JAVA_HOME/bin/java

should list you the file without error.

Check also if logs/ directory is created in your Tigase server location as sometimes unpacking application doesn't create empty directories.

Now when you have the configuration file and databases ready to use you can start the Tigase server with the following command:

./bin/tigase.sh start etc/tigase.conf

If you run the Tigase server installed from sources the command would be:

./scripts/tigase.sh start etc/tigase.conf

There are system startup scripts for Gentoo and Mandriva Linux on bin/ or scripts/ directory which can be used to automatically start the server when system starts.

Now you can register an account on your Drupal website and connect with Jabber client using the account details.

Note! You have to enable plain password authentication in your Jabber client to connect to the Tigase server with Drupal database

Windows installation

Tigase server installation

The server installation should be started with downloading the Tigase server from our download area: http://www.tigase.org/en/filebrowser/tigase-server. This guide describes installation procedure for the branch 3.x of the server so please pick up the latest version of the Tigase 3.x.

The Windows binary package is an executable file containing installer. Run the file and the server will be installed and icons will be added to your Windows start menu. Locate the Tigase group in your menu and execute: "Install Tigase service" which will install the Tigase server as the system service and it will be automatically started whenever your system starts.

If you are going to use the Tigase server with MySQL database have a look now in the directory where the Tigase server is installed. There is a directory etc/. Have a look inside and find file called init.properties. Open the file with a text editor and make sure you added there 2 following lines:

--user-db=mysql
--user-db-uri=jdbc:mysql://localhost/tigasedb?user=tigase_user&password=mypass

The content of the file should look like the example screenshot below:

MySQL database installation

The section describes installation and configuration of the MySQL database to work with Tigase server.

Download the binary package from MySQL download area at address: http://dev.mysql.com/downloads/mysql/5.0.html#win32. Make sure you select executable proper for your operating system.

Run the installation program and follow default installation steps. When the installation is complete find the MySQL elements in the Windows Start menu and run the MySQL Configuration Wizard. Follow the wizard and make sure to check settings with screenshots in guide below.

In Welcome window just press 'Next'.(pic.1)

In the next window select option: 'Detailed Configuration' and press 'Next' (pic. 2)

On the next screen select option: 'Server Machine' and press 'Next' (pic. 3)

On the forth windows leave the default" 'Multifunctional Database' and press 'Next' (pic. 4)

On the step number five just press 'Next' using defaults. (pic. 5)

Again, on window 6 select the default - 'Decision Support (DSS)/OLAP' and press 'Next' (pic.6)

Make sure you switch OFF the 'Strict mode' and and press 'Next' (pic. 7)

On the character encoding page select: 'Manual Selected Default Character set/ Collation' and  'utf8', press 'Next' (pic.8)

On next window select 'Include Bin Directory in Windows PATH' and press 'Next' (pic.9)

On this window just enter  the database super user password and make sure you remember it. When ready press 'Next' (pic. 10)

This is the last screen. Press 'Execute' to save the configuration parameters. (pic. 11)

When the configuration is saved you can repeat all the step and change settings at any time by running: 

START => Programs => MYSQL=> MYSQL serwer machine=>  MySQL Server Instance Config Wizard

Now we have to set Tigase database up. From the Start menu run the MySQL console and enter all commands below finishing them with <ENTER>:

1. Create the database: 
   mysql>create database tigasedb;
2. Add database user: 
   mysql> GRANT ALL ON tigasedb.* TO tigase_user@'%'
                   IDENTIFIED BY 'tigase_passwd';
   mysql> GRANT ALL ON tigasedb.* TO tigase_user@'localhost'
                   IDENTIFIED BY 'tigase_passwd';
   mysql> GRANT ALL ON tigasedb.* TO tigase_user
                   IDENTIFIED BY 'tigase_passwd';
   mysql> FLUSH PRIVILEGES;
3. Load Tigase database schema:
   mysql> use tigasedb;
   mysql> source c:/Program Files/Tigase/database/mysql-schema.sql;

There is a small configuration bug in the installation of the version 3.x. If you look in the run.bat file in the Tigase directory you have to replace string inital.propereties with init.properties.

You can now restart your machine and all services including the MySQL database and the Tigase server should be running. Alternatively if you don't want to restart your computer you can start both services manually if you know how to do it.

When the system is up and running you can connect with any Jabber client (Psi for example) to your server to see if it is working.

Now, you can tweak the server configuration further. Use the guide describing init.properties file for configuration details.

Integrating Tigase server with LibreSource

This document is still not finished.

Taken directly from LibreSource page:
LibreSource is a collaborative platform dedicated to both software development and community building. Based on Java/J2EE technology, LibreSource is a modular web server that users can customize online by combining resources and rights: wiki pages, forum, trackers, files, download areas, etc. All the tools are included and integrated.

Short introduction.

Integration between Tigase server and LibreSource is on database level. It is implemented in the same way as integration with Drupal but with slightly more functions available.

Basically LibreSource system maintains own database with all it's data and Tigase connects to LibreSource database to authenticate users. All users data specific to Jabber/XMPP service are kept in separate tables which can be located in the same database as LibreSource data or in different database.

Current list of features included in the integration:

• Jabber users authentication against user data stored in LibreSource database.
• Recording Jabber user on-line status in LibreSource database. This can be displayed on the Web page as additional user onfo.
• Recording user last login time and this information can also be available on Web page.
• Checking user account status. So if the user account is disabled in LibreSource system then this user will not be able to login to Jabber/XMPP service too.
• User account creation. This feature might be useful during testing time or user data transition from old Tigase installation to LibreSource system. Please note! This feature should be normally disabled on live system. All user account management should be done from LibreSource system because of data caching.
• User account deletion. Please note! This feature should be normally disabled on live system. All user account management should be done from LibreSource system because of data caching.

A few assumptions:

1. LibreSource data are kept in PostgreSQL database - libresource and database user is demo.
2. For use cases where Tigase data are stored in MySQL database name is tigase, database user is dbuser and database user password is dbpass

How to set Tigase up.

Now we will focus on setting things up to have both services up and running together. Below is example of the most complex environment to run where LibreSource is using PostgreSQL database and Tigase is using MySQL database. All basic user data needed for authentication are kept by LibreSource so Tigase has to connect to PostgreSQL database too to authenticate users.

1. First you need LibreSource system up and running. Please refer to LS documentation for details.
2. Install Tigase server in the normal way including loading Tigase database schema. Database tables used by Tigase server use different naming convention so you can simply load Tigase DB schema to the same database as LibreSource data. It is also possible and recommended to keep Tigase data in separate database.
3. Using configuration wizards generate configuration for Tigase server to connect to LibreSource database. Here is the sample file with parameters for configuration wizard assuming following setup:
   • LibreSource data are kept in PostgreSQL database: libresource, user: demo
   • Tigase data are kept in MySQL database: tigase, user: dbuser, password: dbpass
   • No external components are connected to Tigase server
   • Tigase works for domain: domain.net

   ENC="-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8"
   DRV="-Djdbc.drivers=com.mysql.jdbc.Driver:org.postgresql.Driver"
   
   JAVA_OPTIONS="${ENC} ${DRV} -server -Xms100M -Xmx100M "
   TIGASE_CONFIG="etc/tigase-mysql-libresource.xml"
   TIGASE_OPTIONS="--gen-config-def \
     --user-db mysql \
     --user-db-uri jdbc:mysql://localhost/tigase?user=dbuser&password=dbpass&autoCreateUser=true \
     --auth-db libresource \
     --auth-db-uri jdbc:postgresql://localhost/libresource?user=demo \
     --virt-hosts domain.net,localhost "

4. And simpler example where all data (LibreSource and Tigase) are stored in the same database:
   • LibreSource data are kept in PostgreSQL database: libresource, user: demo
   • Tigase data are kept also in PostgreSQL database: libresource, user: demo
   • No external components are connected to Tigase server
   • Tigase works for domain: domain.net

   ENC="-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8"
   DRV="-Djdbc.drivers=com.mysql.jdbc.Driver:org.postgresql.Driver"
   
   JAVA_OPTIONS="${ENC} ${DRV} -server -Xms100M -Xmx100M "
   TIGASE_CONFIG="etc/tigase-mysql-libresource.xml"
   TIGASE_OPTIONS="--gen-config-def \
     --user-db pgsql \
     --user-db-uri jdbc:postgresql://localhost/libresource?user=demo&autoCreateUser=true \
     --auth-db libresource \
     --auth-db-uri jdbc:postgresql://localhost/libresource?user=demo \
     --virt-hosts domain.net,localhost "

Now, you can run Tigase in usual way and all works.

Note! In any case you have to load Tigase database schema for user data. Please refer to guide for specific database: MySQL or PostgreSQL.

Migration from old Tigase installation to LibreSource

Tigase package includes additional tools to make it easier to manage and control you installation. One is used to change configuration settings - config.sh and another is used to manipulate user data in repository - repo.sh.

Depending on whether you use Tigase version built from sources or binary version these scripts might be available in either scripts/ or bin/ subdirectory. To make things simpler let's assume they are stored in scripts/ directory.

Assuming you have old Tigase server installation with number of users in MySQL database and you want to migrate all of them to LibreSource there are 2 steps involved:

1. User data migration
2. Changing your existing configuration

Data migration

First we need to migrate user data used for authentication. That data will be used by both services: LibreSource and Tigase and they normally stored in LibreSource database. Therefore we have to use LibreSource database connector to handle the data (write or read). Tigase server will be using LibreSource database for reading only but during migration time we need to write user accounts to LS database. Sample command to migrate user accounts looks like this:

./scripts/repo.sh -sc tigase.db.jdbc.JDBCRepository \
  -su "jdbc:mysql://localhost/tigase?user=dbuser&password=dbpass" \
  -dc tigase.db.jdbc.LibreSourceAuth \
  -du "jdbc:postgresql://localhost/libresource?user=demo" \
  -cp

Above command will copy all user accounts from MySQL tigase database to libresource database. Please refer to repository management tool documentation for information how to migrate single or selected user accounts.

If you want to also keep all Tigase server data in the same database you have to copy also all other user data like rosters, vCards and so on.

First thing to do we have to load database schema for Tigase data. You don't have to worry. Tigase tables have distinct names from LibreSource so there is no danger for any conflict. As in example above let's assume LibreSource data are stored in libresource database and database user name is demo:

psql -q -U demo -d libresource -f database/postgresql-schema.sql

Now we can load transfer all user data from our MySQL database to LibreSource:

./scripts/repo.sh -sc tigase.db.jdbc.JDBCRepository \
  -su "jdbc:mysql://localhost/tigase?user=dbuser&password=dbpass" \
  -dc tigase.db.jdbc.JDBCRepository \
  -du "jdbc:postgresql://localhost/libresource?user=demo" \
  -cp

This command looks almost the same as a previous one. Just Java class used for handling destination database is different.

Configuration change

Installation

To get server up and running you have to download from our site the most recent version of the binary package.

Unpack it with the following command:

On Unix like system:

tar -xzvf tigase-server-x.x.x-bx.tar.gz

On MS Windows system use any application which can handle either zip files or tar.gz files and unpack server package to selected directory.

Sometimes after unpacking package on unix system startup script doesn't have execution permissions. To fix the problem you have to run following command:

chmod u+x ./bin/tigase.sh

As there are also other useful scripts you could just set executable bit for all of them at the same time:

chmod u+x ./bin/*

Now all you need is Java 6 (1.6 beta2 at the moment) compliant virtual machine. You can run server from command line with simple command:

./bin/tigase.sh run etc/tigase.conf

You can see now a few messages with warning about missing configuration file and missin user repository file. These 2 files will be automaticaly created. Config file will be created just during first execution of the server and user repository file will be created when the first user is added to the system.

You should be able now to connect to the server with Jabber/XMPP client of your choice.

First parameter is a command, second parameter is a config file for startup script. Possible commands are:

• start - Starts server in background redirecting all console messages to separate log file.
• stop - Stops the last started server Be carefull with this command if the server has been stopped in different way but the script still thinks the server is running. The script detects that the server has been started by looking for tigase.pid file. Then it reads server PID from the file and sends kill signal to the process. It may happen that the server is not running but there is another process with this PID. If you know that you server is not running but the script claims it is, it means that the script finds old tigase.pid file. In such case to make it possible to start server again you should either remove the file manually or run script with zap command.
• run - Starts the server as foreground process with all console messages printed onto console. To stop the server simply press Ctrl-C. It does not create tigase.pid file.
• restart - Restarts currently running server. It simply calls the script first with stop command and then with start command.
• check - This commands simply prints all the settings which would be used to start or stop the server. It is strongly recommended to use this command before the first server run.

Config file for startup script simply sets number of environment variables with location of required components. Possible variables to set in this file are:

• JAVA_HOME - location of Java installation home directory. Must be set.
• TIGASE_HOME - location of Tigase installation home directory. By default script try to find this location by searching directories from the location where the script has been run.
• TIGASE_CONSOLE_LOG - file to which all console messages will be redirected if server is run in background. By default it will be: TIGASE_HOME/logs/tigase-console.log. If this file/directory is not writable by Tigase process all console messages will be redirected to /dev/null
• TIGASE_PID location of the file with server PID number. By default it will be TIGASE_HOME/logs/tigase.pid.
• TIGASE_CONFIG - location of the Tigase server config file. This is main config XML file. Not to be confused with startup script parameters file. If not set script trys to find it in following locations in given order: /etc/conf.d/tigase-server.xml, /etc/tigase-server.xml, /etc/tigase/tigase-server.xml or finally in TIGASE_HOME/etc/tigase-server.xml
• JAVA_OPTIONS - options for JVM like size of RAM allocated for the JVM, properties and so on.

You can now proceed to configuration section. Although in simple case installations most of default options should be correct sometimes you need to change server domain name if automatic detection didn't work.

Configuration

This section contains documentation about the Tigase server configuration.

Please note, this guides are for the Tigase server 2.x line which is no longer supported. Please upgrade to the last stable version and contact us if you have any problems.

MySQL database use

This guide describes how to configure Tigase server to use MySQL database as user repository.

If you used XML based user repository before you can copy all user data to MySQL database using repository management tool. All steps are described below.

MySQL database preparation

To load db schema to your MySQL instance first create database:

mysqladmin -p create tigase

And then you can load database schema:

mysql -u dbuser -p tigase < mysql-schema.sql

Server configuration.

Now you have to change configuration to load jdbc module instead of XML based repository. Using configuration management script, first change class name handling repository.
To see current settings run command:

 $ ./scripts/config.sh -c tigase-config.xml -print -key session_1/user-repo-class

As a result you should see something like:

session_1/user-repo-class = tigase.db.xml.XMLRepository

You can see that current setting points to XML repository implementation. To use jdbc module for connection to MySQL database you have to set tigase.db.jdbc.JDBCRepository class (enter text below in one line):

 $ ./scripts/config.sh -c tigase-config.xml -print
      -key session_1/user-repo-class -value tigase.db.jdbc.JDBCRepository -set

As a result you will see new value set for the parameter:

session_1/user-repo-class = tigase.db.jdbc.JDBCRepository

You have also to set the same value as authorization repository unless you want to use different authorization data source:

 $ ./scripts/config.sh -c tigase-config.xml -print
      -key session_1/auth-repo-class -value tigase.db.jdbc.JDBCRepository -set

And again as a result we can see:

session_1/auth-repo-class = tigase.db.jdbc.JDBCRepository

Next step is to set database connection string. Assuming you have database: tigase on localhost with database user: dbuser and password dbpass your connection string will look like this:

jdbc:mysql://localhost/tigase?user=dbuser&password=dbpass

To set this in your configuration file you have to call again configuration management script 2 times. First for user data repository and second for authorization data repository:

 $ ./scripts/config.sh -c tigase-config.xml -print -key session_1/user-repo-url 
       -value "jdbc:mysql://localhost/tigase?user=dbuser&password=dbpass" -set
 $ ./scripts/config.sh -c tigase-config.xml -print -key session_1/auth-repo-url 
       -value "jdbc:mysql://localhost/tigase?user=dbuser&password=dbpass" -set

Note quotes around connection string. They are needed to make sure shell won't interpret special characters.

Now your configuration is ready to load jdbc module and connect to your database.

One more thing you need to do is to tell JVM which jdbc driver to use to connect to database. Depending on your MySQL and jdbc installation it might be: com.mysql.jdbc.Driver. To set is as database driver you have to set is a jdbc.drivers property value. Usually you do this by adding -D parameter to Java call:

 $ java -Djdbc.drivers=com.mysql.jdbc.Driver tigase.server.XMPPServer

If you use tigase.sh script to run server you have to add -Djdbc.drivers=com.mysql.jdbc.Driver to startup script property file to JAVA_OPTIONS values.

User data import

If you previously used XML based user repository you can import all data into MySQL database using repository management tool. This is quite long command so let me list all required parameters first with brief explanation:

1. -cp copy content of the source repository to destination repository.
2. -sc tigase.db.xml.XMLRepository source repository class.
3. -su user-repository.xml source repository connection string - assuming your user repository is in user-repository.xml file.
4. -dc tigase.db.jdbc.JDBCRepository destination repository class.
5. -du "jdbc:mysql://localhost/tigase?user=dbuser&password=dbpass" destination repository connection string.

And now whole command. Enter all in one line:

 $ ./scripts/repo.sh -cp -sc tigase.db.xml.XMLRepository -su user-repository.xml
      -dc tigase.db.jdbc.JDBCRepository
      -du "jdbc:mysql://localhost/tigase?user=dbuser&password=dbpass"

For more information how to use command line administration tools refer to command line tools guide.

PostgreSQL database use

This guide describes how to configure Tigase server to use PostgreSQL database as user repository.

If you used XML based user repository before you can copy all user data to PostgreSQL database using repository management tool. All steps are described below.

PostgreSQL database preparation

Create new database user account which will be used to connect to your database:

# createuser
Enter name of user to add: tigase
Shall the new user be allowed to create databases? (y/n) y
Shall the new user be allowed to create more new users? (y/n) y

Now using new database user account create database for your service:

# createdb -U tigase tigasedb
CREATE DATABASE

Now you can load database schema:

# psql -U tigase -d tigasedb -f postgresql-schema.sql

Now database is ready for Tigase server to use it.

Server configuration.

Server configuration is identical as for MySQL database setup. The same jdbc module is used to connect to PostgreSQL database as for MySQL. The only difference is connection string which usually looks like:

jdbc:postgresql://localhost/tigasdb?user=tigase

So for more detailed guide how to change configuration refer to MySQL database use guide or if you look for more automatic config file generation refer to configuration wizards page.

Command line admin tools

Two command line tools have been created to make it easier to manage server configuration and user repository.

Configuration tool allows to look at configuration settings and modify parameters. It takes care about proper parameters types and encoding.

Repository management tool allows to print repository content for all or for selected users. Modify repository data, add, delete users and copy data from one repository to another.

This guide describe how to efficiently use command line tools which are available for user repository and configuration management.

These 2 command line tools for managing configuration and repository are:

1. config.sh for configuration management.
2. repo.sh for repository management.

Both scripts call class from Tigase package. If you run any of those script with -h parameter you will get help screen describing all available parameters.

I will not concentrate on that help information which is easily accessible anyway. This guide will focus on particular use cases. So it will answer to questions: "How to do it with the tool?".

./scripts/config.sh -h

Parameters:
 -h             this help message
 -c file        configuration file
 -key key       node/key for the value to set
 -value value   value to set in configuration file
 -set           set given value for given key
 -add           add given value to the values list for given key
 -print         print content of all configuration settings or of given node/key
 -f             force creation of the new property - dangerous option...
Samples:
 Setting admin account - overwriting any previous value(s)
 $ ./scripts/config.sh -c tigase-config.xml -print -set -key session_1/admins -value admin1@localhost
 Adding next admin account leaving old value(s)
 $ ./scripts/config.sh -c tigase-config.xml -print -add -key session_1/admins -value admin2@localhost

Note: adding -print option is useful always, even with -set or -add
      option as it prints set value afterwards.

Scripting introduction - Hello world!

This document is the first in series describing scripting support in the Tigase server. It shows how to load, install, update and call a script. It contains also an introduction to the scripting API with the first "Hello world!" like example.

Since the Tigase version 4.3.1 the server supports scripting for administrator commands.

In theory many different languages can be used to write scripts and the only requirement is that the support JSR-223 for the language. More details can be found on the Java scripting project site.

In practise some languages are better supported than others. At the moment the most recommended is Groovy, although following languages are also confirmed to be working: Scala, Python and Ruby. The Tigase SVN contains a few examples for these languages.

Please note, the default Tigase installation contains only libraries for Groovy. Adding support for a different language is as simple as copying a few JAR files to the Tigase libs/ directory.

All the examples presented in this guide are also available as ready to use scripts in the Tigase SVN repository in directory: src/main/groovy/tigase/admin.

The scripting utilises only standard XMPP extensions and is by no means specific to any particular solution. I use and prefer Psi client. The whole guide and all the screenshots are created using Psi client. You can, however, use any other client which supports these extensions as well. As the whole thing is based on the service discovery and ad-hoc commands you need an XMPP client with a good support for both features.

To follow the guide and run all the examples you need installed Tigase server in version at least 4.3.1 and you have to connect to the server as administrator.

Loading script at run time

All the scripting stuff is as usually based on the service discovery and ad-hoc commands in the Tigase server.

The first thing to do, therefore, is to browse service discovery on the running server. The result you receive depends on your installation and installed components.

The most interesting for us right now are all items with "http://jabber.org/protocol/admin" in their node part. You may have a few scripts loaded already but there are two commands used for scripting management. Their names are descriptive anouth I hope: "New command script" and "Remove command script".

The first is for adding a new script or updating existing and the second is for removing script from the server.

To add a new script you have just to execute "New command script". In Psi this is done by double clicking on the element in service discovery list.

The screenshot on the right shows a couple of options to set for the loaded script:

1. Description - is what shows as the script name in the service discovery window. There are no special restrictions on what to put there.
2. Command id - is a unique ID of the script (admin command). This is what shows after the "http://jabber.org/protocol/admin" in node part. This needs to be unique or existing script is overwritten.
3. Language - a drop down list of all supported scripting languages for your installation. The Tigase automatically detects all libraries for scripting languages and lists them here. So all you need is to select correct language for your script.
4. Script text - is just your script content.

When your script is ready and all fields are correctly set, simply press "Finish" button and you should receive a message confirming that the script has been loaded successfully.

In this guide we are creating a simple script of type "Hello world". The script is written in Groovy. What it does is displaying a window (ad-hoc command result) with a message: "Hello admin, how are you?".

It uses a basic scripting API which is described line by line below:

1. It imports basic Tigase classes.
2. Set's a local variable 'p' which points to a 'packet' variable with data received from the client.
3. Creates a 'res' variable which is response sent back to the client (administrator). The response to the client is of type 'result'. Other possible types will be introduced later.
4. We operate on ad-hoc commands here so the script uses Tigase utility class to set/retrieve command parameters. It sets the window title and a simple message displayed to the user (administrator).
5. The last line returns new packet as a script execution result.

The first, very simple version looks like this:

import tigase.server.*
def p = (Packet)packet
def res = p.commandResult(Command.DataType.result)
Command.addTitle(res, "Hello World Script")
Command.addInstructions(res, "Hello admin, how are you?")
return res

Executing script

Once the script is successfully loaded you have to reload/refresh the service discovery window which now should display one more element on the list.

Click on the screenshot on the left to see a full size with all details.

As you can see script name is set to what you have entered as "Description" in script loading window - "Hello world script". The command node is set to: "http://jabber.org/protocol/admin#hello" if "hello" is what is set as the script ID.

To execute the script you just have to double click on the script name (or click execute command if you use any other client).

As a result you should see a simple window similar to the screenshot on the right displaying our message.

Interaction in scripts

Displaying just a message is very nice but in most cases not very useful. Normally you need to ask the user for some more data or parameters before you can perform any real processing.

Therefore in most cases the administrator script has to display a new window with input fields asking the user (admin) for some more data. In this document we present very simple examples, just an introduction so let's ask about the administrator name before displaying greetings.

To ask the user for some more information we have to extend example above with some more code:

import tigase.server.*
 
def p = (Packet)packet
 
def name = Command.getFieldValue(packet, "name")
 
if (name == null) {
  def res = p.commandResult(Command.DataType.form);
  Command.addTitle(res, "Hello World Script")
  Command.addInstructions(res, "Please provide some details")
  Command.addFieldValue(res, "name", name ?: "", "text-single",
    "Your name")
  return res
}
 
def res = p.commandResult(Command.DataType.result)
Command.addTitle(res, "Hello World Script")
Command.addInstructions(res, "Hello ${name}, how are you?")
 
return res

If you compare both scripts you see that they are quite similar. Before displaying greeting, however, the script tries to retrieve data from the 'name' input field. If the name had been provided the greeting is displayed, otherwise the script asks for the user name.

Please note, in this case the packet sent back to the user is of type form instead of result. The practical difference is that the type result displays only OK button which is pressed doesn't send any data to the server. The form packet displays more buttons - Finish and Cancel. Whichever you press some data are sent back to the server.

The script demonstrates use of two new methods from the utility class "Command": getFieldValue and addFieldValue.

• The first argument to all Command methods is the packet with ad-hoc command.
• The second argument is usually the input field name

These two method parameters are actually enough to read the ad-hoc command data. Methods creating input fields in the ad-hoc command need a few arguments more:

• Next arguments sets a default value displayed to the user. The way how it is set in the example above is specific to Groovy language and is quite useful what will be apparent in later examples.
• After that we have to specify the field type. All field types are defined in the XEP-0004.
• The last argument specifies the field label which is displayed to the user.

There are a few other different utility methods in the Command class to set different types of input fields and they will be described in details later on.

To reload the script simply call "New command script" again, enter the script text and make sure you entered exactly the same command ID to replace the old script with the new one.

Or, of course you can enter a new command id to create a new command and make it available on your server.

When the script is loaded on the server, try to execute it. You should get a new dialog window asking for your name as in the screenshot at the beginning of this section. When you entered your name and pressed "Finish" button you see another window and greetings message with your name. 

Automatic scripts loading at startup time

The last thing described in this guide is how to automatically load your scripts when the Tigase server starts. The ability to load scripts at run time, update them and remove is very useful, especially in emergency cases if something wrong is going on and you want to act without affecting the service.

If you, however have a few dozens scripts you don't want to manually load them every time the server restarts.

The Tigase server automatically loads all scripts at the startup time which are located in the admin scripts directory. Unless you set it differently in the configuration it is: YourTigaseInstallationDir/scripts/admin/. All you have to do is to copy all your scripts to this directory and they will be loaded next time the server starts.

But hold on. What about the script parameters: language, description, command id? How are you supposed to set them?

Language is simple. It is detected automatically by the script file extension. So just make sure file extensions are correct and the language is sorted.

The script description and command id needs a little bit more work. You have to include in your script following lines:

AS:Description: The command description
AS:CommandId: command-id
AS:Component: comp_name

Please note, there must be at least a single space after the "AS:Description:" or "AS:CommandId:" string. Everything rest after that, until the end of the line, is treated as either the script description or command id. Put these in your script file and the loader will detect them and set correctly for your script.

Tigase scripting version 4.4.x update for administrators

Scripting functionality is quite useful in the Tigase server for all sorts of administrator tasks. The possibility to load new scripts or replace old ones at the server runtime opens quite new area for the service maintenance.

In earlier versions of the Tigase server scripting capabilities was available only in the session manager component while it might be very useful in many other places - connection managers, MUC, PubSub, VHostManager and what even more important in completely new, custom components created for specific needs. It would be quite wasteful to reinvent the wheel every time and implementing scripting capabilities for each component separately.

Therefore the scripting capabilities has been implemented in the core of the Tigase server. It is now part of the API and is automatically available to all components without any additional coding. A detailed developer guide will be published separately.

This document describes changes from the user/administrator perspective because there are some usability changes related to the new implementation.

 Please note. The description and screenshots are taken from the Psi client and most likely interface for ad-hoc commands and service discovery on other client looks different. I recommend to do some initial testing and experiments using Psi client and then switch to your preferred application for your day-to-day use.

 As it always was in the Tigase you can access all the functions via XMPP service discovery on the server. However, as soon as you connect to the server you can see some changes there.

There are no command on the list. They are hidden from the main service discovery list. You can see on the list only the server main components.

This had to be done for many reasons. One of them is, obviously, the cleaner access to the main server stuff. Another, probably more important, is to avoid a long list of commands for different components mixed together. Commands for different components can have the same name/description and they can even do similar things but they are executed on a different server component. To avoid any confusion and minimise opportunities for mistake the commands are now closely tight to their components. To access a list of commands for a particular component you have to double click on the component name on the list or click 'Execute command" icon on top of the window when your component is selected.

 A new window should show up with drop-down list of available commands. All the commands are related to the selected component and are executed kind of "inside the component environment". You can of course add new command or delete existing one and of course execute any of the commands showing on the list.

As a reminder, in the window title you can see the component ID and you should check it before running any command to make sure you accidentally don't break your system.

 There has been also a small change made to the script adding window. As you can see on the screenshot there is one additional option added - "Save to disk". This means that once you submitted the script to the server it is written to the hard drive and will be automatically loaded at next startup time.

This option is enabled by default as this seems to be a logical choice that the administrator wants to save his new script for later reuse. This, however requires proper configuration of the server and give writing permission to the directory where all scripts are stored. Otherwise the server won't be able to write script files on the hard drive.

As in previous version only users with administrator permissions can execute commands and access all the critical elements on the server. There has been, however, another change made, long time requested by users. In the new version all the administrator specific elements are hidden for the rest of users.

Server components don't show up on the service discovery, the user can't see administrator commands nor he can execute them. This hasn't been implemented to improve the server security but to reduce confusion for general users who would otherwise see a lot of stuff which can't be used by them anyway.

Setting up remote monitoring in the server

The Tigase server can be remotely monitored over following protocols: JMX/RMI, SNMP and HTTP. Even though JMX offers the biggest control and visibility to the server states all of the monitoring services give the same basic set of the server statistics:

• Number of network connections for s2s, c2s and Bosh
• Last second, last minute and last hour load for all main components: SM, MR, c2s, s2s, Bosh, MUC and PubSub
• System statistics - memory usage (heap and non heap) and the server uptime in milliseconds and human readable text.
• Users statistics - number of registered users and number of online user session.

JMX/RMI and SNMP servers offer basic security and can restrict access based and the HTTP server doesn't offer any access restriction mechanisms. Therefore HTTP monitoring is recommended to work behind a firewall.

The monitoring itself causes very low overhead in terms of the resources and CPU consumption on top of the normal Tigase processing requirements so it can be left always on without worrying about performance degradation.

Note. This works with the Tigase server from version 4.2.0 or SVN revision 1418.

What you need.

If you use binary build for version 4.2.0 or later you can skip this section as all required libraries are included in the installation package: Extras pack. Please install the pack and you don't have to worry about libraries any more.

If you run the server from sources or SVN continue reading:

The remote monitoring requires an external library therefore it is implemented in the tigase-extras package to comply with the basic rule - no third-party libraries are needed for the core Tigase server. But still what you need for the remote monitoring activation is just 2 jar files:

1. tigase-extras the last 0.3.0-SNAPSHOT or later
2. jdmkrt.jar file from OpenDMK project version 5.1 or later. A copy of this jar file in also available in our maven repository: jdmkrt.jar.

Download both libraries and put them in the libs/ directory.

Activation.

You can either run the Tigase installer and use configuration wizard to activate the monitoring or edit etc/init.properties file and add following line:

--monitoring=jmx:9050,http:9080,snmp:9060

As you see there is only a single line where you put list of monitoring servers you want to activate. Each server is responsible for activation of a different protocol and takes a single parameter - port number. There are following protocols supported right now:

• jmx - activating monitoring via JMX/RMI
• http - activating monitoring over HTTP protocol
• snmp - activating monitoring over SNMP protocol

You can have all protocols active at the same time or any combination of them or none.

Security

Both JMX and SNMP offer security protection to limit access to monitoring data. The security configuration is a bit different for both.

JMX

After the server installation or in the SVN repository you can find 2 files in the etc/ directotry: jmx.access and jmx.password.

• jmx.access is a user permission file. You can use it to specify whether the user can access the monitoring data for reading only 'readonly' or with read-write 'readwrite' access. There are example entries in the file already and the content may simply look like:

  monitor readonly
  admin readwrite

• jmx.password is a user password file. You can set user passwords here and the format again is very simple and the same as for jmx.access. There are example entries already provided for you convenience. Content of the file may look like the example below:
  

  admin admin_pass
  monitor monitor_pass

Using above to files you can control who and how can access the JMX monitoring services.

SNMP

Access to the SNMP monitoring is controlled using ACL (access control lists) which can be configured in the file  snmp.acl located in etc/ directory. It contains lots of detailed instructions how to setup ACL and restrict access per user, host and what kind access is allowed. The simplest possible configuration may look like this:

acl = {
  {
    communities = public, private
    access = read-only
    managers = public.host.com, private.host.com
  }
  {
    communities = admin
    access = read-write
    managers = localhost, admin.host.com
  }
}

You might also need Tigase MIB definition: TIGASE-MANAGEMENT-MIB.mib for the server specific statistics. The MIB contains definition for all the server statistics exposed via SNMP.

Tigase Tip: Checking the runtime environment

It has happened recently that we have tried very hard to fix a few annoying problems on one of the Tigase installations. Whatever we did, however the problems still existed after uploading a new version and the server restart. It worked fine in our development environment and it just didn't on the target system.

It turned out that due to a specific environment settings on the target system an old version of the Tigase server was always started regardless updates we were uploading. When I finally started looking at the installation the first indication that something is wrong was lack of any log files in place where I expected them.

The best way to check all the environment settings used to start the Tigase server is to use..... check command line parameter:

./scripts/tigase.sh check etc/tigase.conf
Checking arguments to Tigase
TIGASE_HOME = .
TIGASE_JAR = ./jars/tigase-server.jar
TIGASE_PARAMS = etc/tigase.conf
TIGASE_CONFIG =  etc/tigase.xml
TIGASE_RUN = tigase.server.XMPPServer -c etc/tigase.xml --property-file etc/init.properties
TIGASE_PID = ./logs/tigase.pid
TIGASE_OPTIONS = --property-file etc/init.properties
JAVA_OPTIONS = -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8 \
    -Djdbc.drivers=com.mysql.jdbc.Driver:org.postgresql.Driver \
    -server -Xms100M -Xmx200M -XX:PermSize=32m -XX:MaxPermSize=256m
JAVA =  /System/Library/Frameworks/JavaVM.framework/Versions/1.6/Home/bin/java
JAVA_CMD = 
CLASSPATH = ./jars/tigase-server.jar:./libs/jdbc-mysql.jar:./libs/jdbc-postgresql.jar:\
    ./libs/tigase-extras.jar:./libs/tigase-muc.jar:./libs/tigase-pubsub.jar:\
    ./libs/tigase-utils.jar:./libs/tigase-xmltools.jar
TIGASE_CMD = /System/Library/Frameworks/JavaVM.framework/Versions/1.6/Home/bin/java \
    -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8 \
    -Djdbc.drivers=com.mysql.jdbc.Driver:org.postgresql.Driver \
    -server -Xms100M -Xmx200M -XX:PermSize=32m -XX:MaxPermSize=256m \
    -cp ./jars/tigase-server.jar:./libs/jdbc-mysql.jar:./libs/jdbc-postgresql.jar:\
    ./libs/tigase-extras.jar:./libs/tigase-muc.jar:./libs/tigase-pubsub.jar:\
    ./libs/tigase-utils.jar:./libs/tigase-xmltools.jar tigase.server.XMPPServer \
    -c etc/tigase.xml --property-file etc/init.properties
TIGASE_CONSOLE_LOG = ./logs/tigase-console.log

In our case TIGASE_HOME was set to a fixed location pointing to an old version of the server files. The quick check command may be a real time saver.