Tigase Administration Guide

This is the introductory version of MIX specification family

All federated XMPP servers are connected in one global communications network allowing you to send messages to friends who have accounts on other Jabber servers.

This is very much like sending e-mail but the difference between Jabber and e-mail is the same as the difference between sending a traditional mail and talking on the phone.

All messages sent through Jabber are sent instantly and you also receive responses instantly. More over you can see whether your mate is online and available for talking or not.

There exists similar technologies to Jabber like WhatsApp Messenger, Facebook Messenger, Signal, Telegram, WeChat, QQ and other. There are, however, quite a few differences.

XMPP is an open standard which means everybody can know how it works, everybody can implement their own software connecting to the network both client and server side.

The server side is actually the biggest difference and advantage. Many companies have offices in different locations, and such instant messaging technology could be very useful to employees for communication. Companies are not inclined to allow confidential discussions to go outside the company’s network. Especially if it is not very secure to leave such information on third party public servers.

XMPP servers on the other hand, allows you to deploy server software on your own company network. Employees can then talk securely and all information remains on the company’s secure network. Of course if offices are located in different locations or countries then all messages are transmitted over the public network - the Internet. This is not a problem since XMPP supports SSL/TLS - secure encrypted connections which helps you protect your discussion.

Then if your employees need to contact customers outside your company, the whole discussion can go through your server and a server located on the customer side.

There are many other scenarios and use cases but I hope this brief introduction gives you an idea of the differences and advantages of XMPP technology.

You have to install and run a Jabber client application to use the service.

There are multiple domains available: tigase.im, sure.im, xmpp.cloud (and you can host your own domain as well)

The first time you run Psi you see a screen like this:

To connect to tigase.org server we need to configure the program. Below are step-by-step instructions for novice users on how to setup Psi.

Well, you are now connected but how to talk to other people? How to add friends to the contact list? You can send a message to your friends straight away using the Psi menu option New blank message. It is much more convenient however, if you could see which of your friends is online and available for chatting and if you could start talking to your friend just by clicking on his name.

Well done!

You are ready to start Jabbering. Good luck.

Where to go next? For detailed Psi documentation refer to the program Wiki page: http://psi-im.org/wiki/Main_Page

Welcome to the Tigase Administration Guide.

First download Tigase XMPP Server and extract it. You can download the official binaries, or the latest and greatest nightly builds. Once you have the distribution binary extract it and navigate to the directory:

Tigase should start listening on port 8080 - you can check it using lsof command:

You can also check console log under logs/tigase-console.log, which should point you directly to the installer.

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 config.tdsl file on completion of setup process. After this point the setup page will only be accessible using the following:

Point your browser to http://localhost:8080/setup/ unless you are working remotely. You can also use the domain name, or IP address.

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"

The setup consists of several steps that help you configure your installation: selecting features and providing database configuration.

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

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.

You should see a list of listening ports.

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 distribution 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 tigase.bat which will start Tigase using the wrapper. You may also install Tigase and run it as a service.

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

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-<version>-b<build>-<type>.<archive>, where <version> is in the form of major.minor.bugfix, <type> can be either dist (basic package) or dist-max (extended set of components) and archive type can be eitehr tar.gz or zip.

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 these files:

Creating the database is the next step. Previously, we had scripts to handle this process, but we now have the advantage of functions in the tigase.sh script that can be used. Setting up the database can now be done using a single command.

This command will install tigase using a Derby database on one named tigasedb hosted on localhost. The username and password editing the database is tigase_pass and root. Note that -J explicitly adds the administrator, this is highly recommended with the -N passing the password. You may customize this command as needed, refer to the install-schema section of the documentation for more information.

On a windows system, you need to call the program directly:

If this successfully passes, you should see some information printed out

Note at the end, the script will output a recommended example file. You may use this in conjunction with your written config file, but some settings may not be set using this configuration. Again, it is only an EXAMPLE.

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 with the administrator account you setup earlier.

Download the Tigase XMPP Server archive from our repository and extract it to a directory of your choice.

Once that is completed, enter the directory win-stuff and run the setup.bat program. This program when run, will extract the necessary files to appropriate places on your computer. The bat file should look like the following:

To start the server you may use a command prompt from the installation directory

Or you may run wrapper.exe or tigase.bat from the GUI.

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" 'Multi-functional 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>:

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.

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:

The key is as follows:

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

If you don’t want to do all the hosting yourself, you can still have an XMPP service running in your own domain. The only condition right now is proper DNS service record (SRV) configuration that point to the following DNS address: tigase.me.

We highly encourage using SRV records. If you want to register: your-domain.tld on our XMPP service make sure that it resolves correctly:

You can check if the configuration is correct by issuing following commands:

Now, how do you register your domain with our service?

There are a few ways. We recommend checking with the Add and Manage Domains section of the documentation on setting that up. If you cannot or don’t want to do it on your own, the way described in the guide please send us a message, either via XMPP to admin@tigase.im or the contact form requesting new domain. User registration is available via in-band registration protocol. You can also specify whether you want to allow anonymous authentication to be available for your domain and you can specify maximum number of users for your domain.

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:

To set up Tigase XMPP Server as a system service it is required to copy tigase-server.service file to /etc/systemd/system/ directory

This file contains following parameters which may need to be adjusted:

It is also required to copy options file tigase-server to /etc/default/ directory

With those files in place you need to reload systemctl daemon

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.

Upon shutdown, statistics for the server’s runtime will be appended to the log file. For a description of the statistics 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 config.tdsl file:

Starting with v8.0.0 you can now shut down individual cluster nodes without shutting down the whole server. This command will use the SeeOtherHost strategy to direct traffic to other nodes and update the cluster map to gracefully shut down the single node

Shutting down individual nodes can be done VIA Ad-hoc command and fill out the response forms. The command is available from message-router as http://jabber.org/protocol/admin#shutdown.

As with any migration it is highly recommended that you backup your repository before conducting any upgrade operations.

For MySQL databases:

After downloading Tigase XMPP Server 8.0.0 from our website, or using wget, extract the files to a separate directory.

Copy the tigase.conf and init.properties files from the old directory to v8.0.0 directory.

Import the database.

Tigase XMPP Server has a utility that can be called using upgrade-config that will update your old init.properties file and create a new file using DSL.

When everything is ready it will printout following information

Edit your new config.tdsl file to connect to the new database you created during the import step.

Upgrading database schemas is now possible using the upgrade-schema option. Do this now.

You will be asked the following prompts:

Upon success, you should see the following:

Start Tigase!

Both upgrade commands also have a build in help function, they can be called if needed from the command line. You can also run these commands for help.

To make upgrade process easier it’s possible to utilize tigase-upgrade.sh *nix shell script. It permits upgrading to new version (supports downloading version from provided URL).

It’s usage is as follows:

Where: * {upgrade|rollback} - defines whether to perform upgrade or rollback to previous version * install_package - package to which perform upgrade (can be URL) in case of upgrade or backed-up installation (from which we want to restore) in case of rollback * install_directory - destination directory (both in upgrade and rollback); can be symlink in which case it will be preserved with upgraded/restored path as target * [tar|dir] - (optional) type of backup (either simply copy directory or also archive it using tar command); by default dir is used.

To upgrade installation to version tigase-server-8.0.0-SNAPSHOT-b5285-dist-max.tar.gz execute the script as follows:

To rollback from tigase-server-8.0.0-SNAPSHOT-b5264_backup-18-11-05_1712 backup execute script as follows:

In properties configuration format each line contained key and value with optional definition of type of stored value:

where c2s/ports was name of property, [i] defined that type of value is array of integers, and 5222,5223 was comma separated list of values.

This format worked but in fact c2s/ports was not name of property you configured but key which was later split on / char to parts which defined by names path to property which name was in last part. From that you can see that it was domain based setting of properties.

Except from this multi-part keys we also used properties starting with -- which were global properties accessible for every part of application, i.e.: to add new component and set some properties you needed to write:

This lead to mistakes like duplicated definition of name and class for same number of component or redefined property value in other place of a configuration file - especially in cases where configuration was big.

In this configuration structure it was hard to tell where is configuration for particular component or what databases this installation uses. This could be defined all over the file.

In this release we are introducing Tigase Kernel Framework, which allows to configure beans in configuration file and even define usage of new beans loaded from external jars which can modify behavior of Tigase components. This would make configuration file even more complex, difficult and less readable.

DSL stands for domain-specific language - in this case language created for storage of configuration.

Now we use domain based configuration which means that our configuration file is not a flat key=value storage but it defines objects, it’s properties and assigned values.

To illustrate it better let’s start with a simple example. In properties file in order to configure PubSub component named pubsub you would use following properties:

In DSL based configuration this would be replaced by following block

in which we define bean with name pubsub and set it’s class inside () block to tigase.pubsub.PubSubComponent. We also use block between {} chars to define properties which are related to bean. Which means this properties will be passed only to this instance of Tigase PubSub Component, same as it was before where we needed to add prefix. Entries after # are comments, to pass # you need to wrap whole part containing it in '', ie. 'test#242'

DSL configuration format provides a number of advantages over the old system of configuration. . All configurations for components are related in a single block, so they are not spread out over several different lines. . No need for long property names, no longer have to invoke a long string of settings for multiple values. . Support is provided for environment variables. . No longer need to escape certain characters, making settings far more readable at a glance. . Values may be set using basic calculations, such as 100 * 200 * 2 rather than 40000. . Parameter type values are no longer necessary, no more [i], [S], [B] etc.. . Comma separated values can now be simplified lists with separate entries being able to be in multiple lines.

Although the format may seem more complex, looking like a section of java code, the formatting is consistent and can be far more readable. After some experience with DSL format, you’ll find it’s far more intuitive and user friendly than it may appear. Of course if there’s any real confusion, Tigase can automatically convert old style properties files to the DSL format using the following command:

Tigase XMPP Server is packaged with a basic config.tdsl file that tells the server to start up in setup mode.

This tells Tigase to operate in a setup mode, and tells the http component to allow login with the username and password admin/tigase. With this you can enter the setup process that is covered in this section.

There are other options for config-type: default, session-manager, connection-managers, and component. For more information, visit Config Type property description.

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 Using TCP keepalive to Detect Network Errors and TCP Keepalive HOWTO some keepalive settings should be changed to improve reliability - it will enable keep alive functionality (checking if the connection is established and valid) and, by decreasing times and interval - will make detection of broken connections faster.

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.

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 roughly 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 organized 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 config.tdsl file:

Logic Options are:

The threadsNo property allows you to fine-tune the SM plugin’s (processors) thread pool. With the default settings every plugin gets his own thread pool. This guarantees the best performance and optimal resource usage. The downside of this setting is that packets can arrive out of order if they are processed within different thread pools.

We can even fine tune this packet processing. Let’s say you want most of the plugins to be executed within a single thread pool to preserve packet ordering for them, but for some selected plugins that should execute within separate thread pools to improve performance. Let’s say, authentication packets and user registration can be actually executed in a separate thread pools as we do not worry about an order for them. Users cannot send or receive anything else before they authenticates anyway. The solution is to specify a number of threads for the selected plugin. For example, setting a common thread pool for all plugins but registration and authentication can be done with following configuration:

This replaces the old --sm-threads-pool property, as well as specifying thread pools in --sm-plugins.

Session manager can control the number of available thread pools for each processor. By adding the following line to the config.tdsl 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.

The Strategy property allows users to specify Clustering Strategy class which should be used for handling clustering environment; by default SMNonCachingAllNodes is used.