Tigase Administration Guide

Tigase v7.1.1 includes changes made for v7.1.0, so below is included major changes and highlights for v7.1.0 of Tigase. The lists of specific fixes will not be included in this documentation.

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

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. You may be confused at the beginning as there are lot of choices, but 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

On most systems installing JRE or JDK creates a default association which allows to run the .jar file by just 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:

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

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

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

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.

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.

Next important step is package selection. Note that some choices are grayed out and you cannot change them as they are essential. Packages consist 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 that you 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 database along with also included drivers.

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

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.

From here you can select which components will be installed. For most installations the default selection will be 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 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 to separate user groups, for example ones from different organizations.

When you 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 use admin, however you may choose any name you like. For example for domain tigase.org the full admin name would be admin@tigase.org. Just stick your chosen name and domain together using the @ character as separator.

Using this information your XMPP admin will be automatically added to the database, so after installation you can just login into the server without registering admin first 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 is easy for a hacker to guess.

Important notice: Tigase installer does not contain the actual databases, only drivers allowing db access. The only 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.

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 cannot go beyond this step after trying to resolve database problems you may try manual installation mode.

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.

Part of the installation process is the selection of Tigase base directory. This is where you can find all important server files. The 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:

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

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.

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

First download Tigase XMPP Server and extract it. You can download the official binaries, or the latest and greatest nightly builds.

Please do not run as root.

You should see a list of listening ports.

Some points before you can connect:

This setup page is restricted access, however for first setup there is a default account set to setup Tigase: Username: admin Password: tigase

This combination will only be valid once as it will be removed from init.properties file on compleation of setup process. After this point the setup page will only be accessable using the following:

Point your browser to http://localhost:8080/setup/ unless you are working remotely. Then you can use the domain name, or IP address. I used http://tpub.xmpp-test.net:8080/setup/ for this guide.

Enter the username and password above to gain access.

You will be greeted by the following "About software" page.

Read it and then click "Next"

Here is some information about our commercial products and licensing. Please read though the agreement, type your name or company and click "Next".

This page will look over your default configuration settings, these include the type, Domains you wish to use, and gives you a chance to specify an administrator for the domain. Also, you will be selecting what type of database Tigase server will be using.

The Advanced configuration page. Select what components and configurations you need.

Plugins which will be loaded by the server, most plugins are enabled by default.

This is where the database schema is installed. BE SURE TO SPECIFY SUPER USER ACCOUNT AND PASSWORD

You should see a page like this after a successful database setup. This page will reveal any issues with your database setup such as invalid URIs, passwords, and schemas.

Next a page asking if you’d like to provide an API Access Key to access HTTP REST commands. It is highly recommended that you either specify an API key or block access. Open API keys allow any REST command to be interpreted by the server.

The Setup Access Page will be locked from the admin/tigase user as specified above. This is your chance to have the setup pages add a specific user in addition to admin accounts to re-access this setup process later. If left blank, only JIDs listed in admin will be allowed to access.

The installation is complete and this is what the init.properties file will look like. If you have a custom setup, or would like to put your own settings in, you may copy and past the contents here to edit the current init.properties file. Click "Save" to write the file to disk.

You have now finished the installation, proceed to the next step to restart the server.

It is recommended at this point to stop the server manually and restart it using the proper script for your OS. From the Tigase base directory enter

where {OS} is your type of Linux, gentoo, debian, mandriva, or redhat

To further fine tune the server you should edit etc/tigase.conf. Ensure JAVA_HOME path is correct, and increase memory if needed using JAVA_OPTIONS -Xmx (max), and -Xms (initial). You will need to direct Tigase to read settings from this file on startup as follows.

Everything should be running smooth at this point. Check the logfiles in logs/ if you experience any problems.

There are a few steps involved with setting up Tigase with the web installer in a Windows environment. Please follow this guide.

First step is to extract the dist-max archive in it’s entirety to the intended running directory. Once there, run the Setup.bat file inside the win-stuff folder. This will move the necessary files to the correct folders before Tigase begins operation.

From here, you have a few options how to run Tigase; run.bat will operate Tigase using a java command, or run.bat which will start Tigase using the wrapper. You may also install Tigase and run it as a service.

One this setup is finished, web installer will continue the same from here.

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 bandwidth requirements or user preferences. Due to popular demand, the Tigase development team has decided to implement a console installer for the server.

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

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 download the latest version (highest version number) of the server as it contains latest functions and improvements.

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

Now you are ready to to install the server.

Some tips for working with the console installer:

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 file using command for the tar.gz file:

or for the zip file:

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:

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

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

A Small change in the tigase.conf file is needed. Find the line setting for JAVA_HOME:

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 this is a manual installation, you will have to edit this document yourself. It contains already a few lines:

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

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 section of the Tigase Server guide.

You will 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:

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

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/db-create-derby.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:

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.

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

You can start the server using the tigase file found in the scripts sub-directory of Tigase server base directory. There, select the type of linux you have, debian, gentoo, mendriva or redhat. In the root server directory type the following command:

Where {OS} is your *nix operating system.

and you should get the output like this:

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:

The first 2 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 an 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.

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

Download the binary package from MySQL download area at mysql.com. 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 against the screenshots in the 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 steps and change settings at any time by running: START ⇒ Programs ⇒ MYSQL⇒ MYSQL serwer machine⇒ MySQL Server Instance Config Wizard

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

There is a small configuration bug in the installation of Tigase 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 XMPP 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.

You will not be able to use an IP Address or a CNAME record to setup an XMPP Server. While it’s not required, an A record can provide some other benefits such serving as a backup in case the SRV record is not configured right.

You will need to set SRV records both for client-to-server (c2s) communication and, if you plan to use it, server to server (s2s) communication. We recommend both records are entered for every server as some resources or clients will check for both records. For this example we will use tigase.org is our domain, and xmpp as the xmpp server subdomain.

SRV records have the following form:

_service._protocol.name. TTL class SRV Priority weight port target.

The key is as follows:

For our example server, the SRV records will then look like this:

_xmpp-client._TCP.tigase.org 86400 IN SRV 0 5 5222 xmpp.tigase.org

_xmpp-server._TCP.tigase.org 86400 IN SRV 0 5 5269 xmpp.tigase.org

If you have a cell phone on a separate network with an XMPP client, you can now try to login to test the server. If that is not handy, you can use an online tool to check proper DNS records such as kingant’s: https://kingant.net/check_xmpp_dns/ and it will tell you if anything is missing.

Once your server is setup, you may need to open at least two ports. By default XMPP communication happens on ports 5222/5269, to which point SRV records. Other ports used by the server are:

If for any reason you can’t use default ports and have to change them it’s possible to point SRV records those ports. Please keep in mind, that you have to open those ports for incoming connections in your firewall. In case you are using iptables you can use following command to include those ports in your rules:

Both ports should be setup to use TCP only. If for any reason you want to make service available for different ports you can:

Once you’ve located the appropriate distribution scripts (please take a look at the table above), copy it to your system’s init.d folder (usually it’s /etc/init.d/):

You may also need to make it executable:

It is recommended that you open the script files or configuration files as some have some parameters that you will need to specify.

There are a number of benefits to running Tigase as a service, one of which is to ensure that the program will run even in the event of a power outage or accidental server restart, Tigase will always be up and running.

Once installation is complete, you should be able to start Tigase using the following command:

Tigase should begin running in the background. Since Tigase is now installed as a service, it can be controlled with any of the service commands, such as:

Upon shutdown, statistics for the server’s runtime will be appended to the log file. For a description of the statsitics and what they mean, refer to the Statistics Description portion of the documentation.

To aid with troubleshooting purposes, the full stacktrace will be dumped to a seperate file located at $serverdir/logs/threads-dump.log.# Stacktrace logs will follow the same log file numbering scheme described in Log file description.

This feature is enabled by default, however you may disable this by adding the following to your init.properties file:

The fs.file-max kernel property is set via sysctl command. You can see current settings by executing the command:

If you plan to run high load service with large number of server connections, then this parameter should be at least as twice big as the number of network connections you expect to support. You can change this setting by executing the command:

You can see current settings by executing the command:

You can change this setting by executing the command:

According to blog.kolargol.eu or www.gnugk.org/ some keepalive settings should be changed to improve reliability.

The above commands let the system remember new settings until the next system restart. If you want to make the change permanent you have to edit the file: /etc/sysctl.conf and add the property at the end of the file:

It will be automatically loaded next time you start the server.

Command:

Causes the /etc/systcl.conf to be reloaded which is useful when you have added more parameters to the file and don’t want to restart the server.

This is the property used by the system limits. For example running the command ulimit -a shows you all limits set for the current user:

To make it even more interesting and more complex, there are 2 types of system limits: soft limit which can be temporarily exceeded by the user and hard limit which can not be exceeded. To see your hard limit execute command:

The hard limits are usually bigger then the soft limits or sometimes the same.

For us the most important parameter is: open files. You can change the property in file: /etc/security/limits.conf. You have to append 2 following lines to the end of the file:

Where the jabber is the user name of the account running you IM service. You can also set the limits for all users on the machine in a following way:

For those changes to make an effect you have to logout from the modified account and login again. New limits should be applied.

If one intends to use init scripts for startup purposes (or simply wants to be able to start the server utilizing su command) it’s necessary to adjust PAM configuration by modifying /etc/pam.d/su file and uncomment following line:

Afterwards the init scripts will respect configured limits.

By default Tigase server loads tigase.conf.ConfigurationCache class which stores the whole configuration in memory. Please note that the init.properties file with initial settings is always loaded if it is available at the given location and all settings in this file work exactly as before. For more details, please refer to the online documentation.

A couple of times 'initial configuration' and 'whole configuration' were mentioned. What is this about, what is the difference?

The 'initial configuration' are startup settings provided by the user in the init.properties file. Most of the server elements use far more configuration parameters which are set to sensible default values if they are not provided by the user. The configuration framework in Tigase server always keeps the complete configuration of all active elements. This is implemented in such a way to make it possible to present currently used settings to the end-users or administrators and allow them to change the server parameters during runtime.

There is one more configuration storage implemented right now. It allows you to store the server settings in the SQL database. In most cases this is not quite useful, just opposite, very inconvenient. However. there is at least one case where you really want to keep the server configuration in the SQL database. This is in the cluster mode. If you have a Tigase cluster system of 10 or more nodes it is much easier to keep the configuration in a single central location and manage it from there, rather then go to every single machine every time you want to change some settings. You can even change any settings for all cluster nodes with a single database query.

You set the SQL storage the same way as you set it for XML file. However, there is one more parameter as you have to provide also database connection string for the server so it knows where to connect to for the settings:

Please note, the current implementation for the SQL storage automatically creates the tables necessary to operate if it does not exist. So you don’t have to worry about the schema, but you should make sure that the database user used by the Tigase has permissions to create a table.

Configuration is stored in table with following schema:

While using the tigase.xml file is still possible and the old behavior can be preserved, it is now disabled by default. By default the Tigase server reads only init.properties file with initial settings and stores all the complete configuration in memory only.

The init.properties works exactly as before and all old parameters are still working exactly as before. The only difference is the lack of the tigase.xml which is not created or read by default if it is present. The main advantage is that you don’t have to remove it each time you change something in the init.properties to pick up new settings.

Firstly we will go into how to re-enable the server to check and use the tigase.xml file to retain functionality with older settings. This is actually very simple to accomplish. The Tigase server now, offers pluggable repository support. This means that you can easily extend current functionality with a different configuration storage by writing own class which reads and writes configuration parameters.

By default class tigase.conf.ConfigurationCache is loaded which stores configuration in memory only.

Please note, the init.properties file is always read if it exists at a given location.

To revert to the old behavior you just need to pass a parameter to Tigase server with a class name which is responsible for keeping server parameters in the old XML file. You can do it in two ways:

As the configuration mechanism in the Tigase server offers pluggable storage engines, you can easily write your own engine by implementing the interface: tigase.conf.ConfigRepositoryIfc or by extending one of current implementations.

The whole configuration framework is pluggable and you can replace it completely if it does not suit you well enough. Your implementation has to extend tigase.conf.ConfiguratorAbstract class and can be set using JVM system property (as this is configuration framework you can’t do this via any configuration system):

The example above shows the parameter set to the default configuration framework.

The Message router component was the only component which was fixed to the Tigase instance. In theory it could always have been replaced but in practice there was no way of doing it as that was the first element loaded at startup.

Now Tigase message router implementation can be easily replaced to and it can be made a configurable option if needed.

At the server startup time the code creates configurator and calls method: getMessageRouterClassName() which by default returns class: tigase.server.MessageRouter. You can extend the configurator and provide any different class name instead which implements required interfaces. You can even make it configureable as it is no longer tied to the server instance.

For the non-production deployments (development or stating environments) we recommend using default memory settings of the JVM (which depends on the underlaying operating system), which result i automatic memory allocation and, by the rule of thumb - are the safest in such environments.

For the production environments we recommend a fixed size HEAP - both initial and maximum size, which can be set with (respectively)-Xms and -Xmx JVM flags - ideally to the same value (which should be roughtly 95% of the available memory, if Tigase will be the only service on the machine) to avoid allocation and deallocation.

For convenience it’s possible to uncomment line with PRODUCTION_HEAP_SETTINGS and adjust parameters accordingly.

Let’s start with stating that there is no "one to rule them all" - each deployment and use-case is different, however we will try to give a couple of pointers and recommendations proceed with short introduction to GC itself.

XMPP is quite specific in terms of memory allocation - short-lived objects (various types of stanzas) usually exceed number of long-lived objects (user connections and related data). This is important bit of information in the context of how usually JVM HEAP is organised and how Garbage Collector works. On the most basic level Heap is separated into couple of regions:

By default, Tigase employs XEP-0352 Client State Indication which allows for a more streamlined mobile experiencing by allowing the XMPP server to suppress or reduce the number of updates sent to a client thereby reducing the number of stanzas sent to a mobile client that is inactive. This employment is contained within the processor ClientStateIndication and is independent from the MobileV1, MobileV2, MobileV3 settings.

However, this can be fine tuned by using mobile plugins from Tigase which can be used at the same time by adding the following line to the init.properties file:

Options are:

Session manager can control the number of available thread pools for each processor. By adding the following line to the init.properties file, the global thread pool can be increased by a specified factor:

In this case, the global thread pools is increased by a factor or 3.

LetsEncrypt is a trusted CA that provides free security certificates. Unlike previously self-signed certificates, we can use LetsEncrypt Certificates to certify your domains from a trusted source. To do this, remote into the server hosting Tigase, or login to the computer locally and begin to install git if that is not already on the system.

Once the machine installs git, use the following command to download the LetsEncrypt Tools.

This will download the tools into the computers' /opt/letsencrypt directory. You will now need to generate the certificates using this tool using the next command.

where domain.com is your currently hosted domain. Be sure that port 443 is forwarded to this computer, and that proper A and DNS records are registered for your domain.

Those certificates will be created and will be stored in /etc/letsencrypt/live/$domain and you will need admin privladges to see them.

In that directory, you will find four certificates: - cert.pem - chain.pem - fullchain.pem - privkey.pem

For Tigase, we are only concerned with privkey.pem contents. Copy that certificate to another directory.

At this point we will need to obtain the root and intermediate certificates, this can be done by downloading these certificates from the LetsEncrypt website.

Alternatively, you may obtain them using wget:

These are the root certificate, and the intermediate certificate signed by root certificate. NOTE: IdenTrust cross-signed certificate will not function properly.

Take the contents of your privkey.pem, and combine them with the contents of isrgrootx1.pem and letsencryptauthorityx3.pem into a single pem certificate. You may wish to name the file after your domain such as mydomain.com.pem. Your certificate should look something like this:

Place that certificate into your /certs folder of Tigase, and installation of this certificate is done.

You will need to do this for all subdomains you wish to have a certificate for, however, you may be able to import the root and intermediate certificates to your keystore to avoid having to paste the chain certificates for each subdomain.

The Tigase Auth connector with shortcut name: tigase-auth is implemented in the class: tigase.db.jdbc.TigaseAuth. It allows you to connect to any external database to perform user authentication. You can find more details how to setup a custom connector in the Custom Authentication Connectors guide.

To make this connector working you have to prepare your database to offer set of stored procedures for Tigase server to perform all the authentication actions. The best description is the example schema with all the stored procedures defined. Please refer to the Tigase SVN repository for the schema definition files.

Files with the stored procedures implementations are located in postgresql-schema-4.sql file for PostgreSQL database.

The absolute minimum of stored procedures you have to implement is:

With these 2 above stored procedures you can only perform user login/logouts on the external database. You can’t register a user account, change user password or remove the user. In many cases this is fine as all the user management is handled by the external system.

If you however want to allow for account management via XMPP you have to implement also following procedures:

The Tigase Custom Auth connector with shortcut name: tigase-custom is implemented in the class: tigase.db.jdbc.TigaseCustomAuth. It allows you to connect to any external database to perform user authentication and use a custom queries for all actions.

You can find more details how to setup a custom connector in the Custom Authentication Connectors guide.

The basic configuration is very simple:

That’s it.

The connector loads correctly and starts working using predefined, default list of queries. In most cases you also might want to define your own queries in the configuration file. The shortest possible description is the following example of the content from the init.properties file:

Queries are defined in the configuration file and they can be either plain SQL queries or stored procedures. If the query starts with characters: '\{ call' then the server assumes this is a stored procedure call, otherwise it is executed as a plain SQL query. Each configuration value is stripped from white characters on both ends before processing.

Please don’t use semicolon ';' at the end of the query as many JDBC drivers get confused and the query may not work.

Some queries can take arguments. Arguments are marked by question marks '?' in the query. Refer to the configuration parameters description for more details about what parameters are expected in each query.

The first example shows how to put a stored procedure as a query with 2 required parameters.

The same query with plain SQL parameters instead:

The order of the query arguments is important and must be exactly as described in specification for each parameter.

Currently, we can only check authentication against a Drupal database at the moment. Full Drupal authentication is not implemented as of 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 a Drupal database based authorization is located in tigase.db.jdbc.DrupalAuth class. Although this class is capable of adding new users 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. Functionality for adding new users is implemented only to ease user accounts migration from different repository types from earlier Tigase server installations.

The purpose 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 XMPP even if user provides valid password.

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

From version 5.1.0, rev. (build) 2881 Tigase XMPP Server offers support for authenticating users against an LDAP server in Bind Authentication mode.

Configuration for the LDAP support is really simple you just have to add a few lines to your init.properties file.

Please note the USER_ID element, this is a special element of the configuration which is used to authenticate particular user. Tigase LDAP connector replaces it with appropriate data during authentication. You can control what Tigase should put into this part. In your configuration you must replace this string with one of the following:

In order to enable SASL External add following line to the init.properties file

File cacert.pem contains Certificate Authority certificate which is used to sign clients certificate.

Client certificate must include user’s Jabber ID as XmppAddr in subjectAltName:

It is possible to make client certificate required:

If this option will be enabled, then client must provide certificate. This certificate will be verified against c2s/clientCertCA. If client does not provide certificate or certificate will be invalid, TLS handshake will be interrupted and client will be disconnected.

Using this options does not force client to use SASL EXTERNAL. Client still may authenticate with other SASL mechanisms.

Domain based packet filtering is a simple filter allowing to restrict user communication based on the source/destination domain name. This is especially useful if we want to limit user communication within a single - own domain only or a list of domains.

A company might not wish to allow employers to chat during work hours with anybody in the world. A company may also have a few different domains used by different branches or departments. An administrator may restrict communication to a list of domains.

Included with Tigase is the dbSchemaLoader Utility, which can be used to apply schema files to databases. It is able to operate with Derby, MySQL, SQLServer, and PostgreSQL databases. In order to use this utility with any of the databases, you will need to first have the database environment up and running, and have established user credentials. You may use root or an account with administrator write privileges.

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

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

This guide describes how to prepare the MS SQL Server database for connecting the Tigase server to it.

This guide describes how to prepare PostgreSQL database for connecting to Tigase server.

Tigase now supports MongoDB for auth, settings, and storage repositories. If you wish to use MongoDB for Tigase, please use this guide to help you.

Connect to your database from a command line and execute following statement for MySQL database:

Where encoding mode is one of the following:

For example:

The way passwords are stored in the DB is controlled by Tigase database schema property. Properties in the database schema can be set by a stored procedure called: TigPutDBProperty(key, value). Properties from the DB schema can be retrieved using another stored function called: TigGetDBProperty(key).

The simplest way to call them is via command-line interface to the database.

For the purpose of this guide let’s say we have a MySQL database and a test account: test@example.com with password test77.

By default, most of DB actions for Tigase, are performed using stored procedures including user authentication. So, the first thing to do is to make sure the stored procedures are working correctly.

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 with Tigase server.

The easiest way to setup Tigase server for connecting with MySQL database is to use the 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 describes an older way for using configuration generators which is a bit more difficult and doesn’t work on Windows systems. The guide below describes a new way to use them which is simpler and can be applied to Windows systems as well. It is using the init.properties file where you can put all your initial configuration parameters.

This guide describes MySQL database connection parameters.

This 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:

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:

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

Tigase supports integration with Drupal on many levels. At the moment this guide can 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, Tigase can authenticate users against a Drupal database which means you have the same user account for both Drupal website and the XMPP server. Moreover 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 followed by Tigase server too.

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.

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

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

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

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

We had to make a small change to the database schema for Tigase version 5.1.0.

It does not affect data or data structure, only the way in which some data is accessed in database. We added one more stored procedure which has to be installed in database if you upgrade your installation from a previous Tigase version

The schema upgrade is very simple and safe but make sure the current database schema is in version 4.0. If you happen to use ancient version of Tigase earlier than 4.0 and you want to upgrade to 5.1, you have to run 4.0 upgrade script first.

Please follow detailed guide for the database applicable to your installation: Derby, MySQL, PostgreSQL.

The schema upgrade is very simple and safe but make sure the current database schema is in version 4.0.

First things first - make a database backup:

If you need to restore database for any reason simply extract files from the backup archive:

Now we can run schema upgrade script

The schema upgrade is very simple and safe but make sure the current database schema is in version 4.0.

Assumptions:

First things first - make a database backup:

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

Note! You may be required to use root user and his password to execute mysqladmin commands.

Now we can run schema upgrade script

The schema upgrade is very simple and safe but make sure the current database schema is in version 4.0.

Assumptions:

First things first - make a database backup:

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

Now we can run schema upgrade script

We have recently made a simple but very useful change to the DB schema in Tigase. It preserves backward compatibility and so your existing schema does not need to be changed, even if you upgrade your installation to the most recent 5.1.0 version.

However, the change is can help to track new accounts creation, therefore this article shows how to make modifications to you schema manually.

The change is related to adding a new field: acc_create_time which stores exact time of user account creation. The time is recorded automatically by the database when a new record in the user table is created. This allows for no extra overhead or resource usage on Tigase.

Along with the new field, there are slight modifications to 2 other fields: last_login and last_logout.

Here is how it looks now:

You can easily update your schema with above changes using a simple SQL query. Enter the MySQL shell and copy-paste following query:

Please note, after executing query above the column acc_create_time will have a null value. To populate the entry for existing records just copy last_login value to acc_create_time:

Schema Upgrades for Tigase server version 4.x.

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

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 the new version of Tigase server in a few minutes or even seconds depending on your database size. It took around 7 minutes to update our database with 200k user accounts on an average machine.

Note. Do not update the database schema before Tigase server tells you to do so. Be sure to do a database backup before starting the schema update.

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

Assumptions:

First things first - make a database backup:

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

Note! You may be required to use root user and 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:

The script should generate output like this:

The module itself doesn’t do anything, it just schedules tasks and sends stanzas which come from anywhere. To do the 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 practice 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:

StanzaSender is a Tigase component so the configuration is similar to that of all other components. The simplest way to get the settings for StanzaSender is by generating a 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:

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

And the main settings section for the component:

Most parameters should be pretty clear but some may need a little explanation.

The HTTP API Requires Tigase version v5.0.3 but we recommend using the latest version of Tigase which will give you the easiest setup and functionality. Current versions of Tigase include most of the required files needed to run the API, however you will need to add one more library: servlet-api-3.1.jar which is available Here. Place that file in your /jars directory and you’re all setup and good to go.

Please note, earlier versions of Tigase installer may have not included another required file: javax.servlet-api.jar

This file is included in the archive distributions, and may be extracted to the /jars directory from there.

For older versions of the API, please see the Tigase HTTP API Wiki.

Once all the requirements in place, all you need to do is add the following lines to Tigase’s init.properties file:

Note that the class and name number is not important, so long as you don’t have anything else with the same number.

With this default configuration Tigase will attempt to start an http server at port 8080 and run the default modules such as RestModule which will add context for the REST API in /rest path. RestModule will also load all groovy scripts located in scripts/rest/xxx directories and it will bind it to proper action for the /rest/xxx/ paths. More than one directory can be used, think of xxx as a wildcard.

To begin using the HTTP API, point a browser to the following url http://your.server.domain:8080/ui/ and you will be presented with the following image to login with.

Use your admin-level XMPP id and it’s password to login. Please use bare JID for logins.

NOTE: Normal users can login here as well to use chat and basic functions, but they will not have admin privileges as shown in this guide

Scripts in the HTTP API component are used for processing all of requests.

To add a new action to HTTP API component you need to create a script in Groovy in which there is an implementation of class extending tigase.http.rest.Handler class. The URI of the script will be created from the location of script in scripts folder. For example, if TestHandler script with regular a expression will be set to /test and will be placed in scripts/rest/tested, the handler will be called for following URI /rest/tested/test.

This component covers both REST API as well as basic HTTP component configuration. REST stands for REpresentational State Transfer which is a stateless communication method that in our case passes commands using HTTP GET, PUT, POST, and DELETE commands to resources within the Tigase server. Although REST uses HTTP to receive commands, REST itself is not intended for use in a browser.