Configuration details

If you look inside configuration file you can see that this is just normal XML file with a few top-level separate sections. These sections are called components.

This is it. Tigase server consists of components and without components there is no application at all. This is why the only configuration settings you can find there are only under some component level.

More precisely top level element in this XML file is called: <tigase-config/> and it doesn't contain any top level configuration settings.

Under the top level element there are at least 2 or more <component/> elements. Each component can be distinguished from others by it's 'name'. That is, 'name' attribute is mandatory and must be distinct within configuration file. It is just component ID. Each component can be named any way you like it doesn't need to mean anything. It is just easier to manage configuration if you select sensible names.

<component/> elements keep configuration settings for server modules.

Example 1:

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

Configuration settings are kept in "simple" maps like structures (key, values, type) triplets.

• key is a configuration parameter identifier or a name of the parameter
• values are just values of the parameter identified by the key. Usually this is just a single value but in some cases there can me more than just one value.
• type all configuration parameters have a type. In most cases this is just a String. Other possible types are: Boolean, Integer, Long and corresponding array types: String[], Boolean[], int[], long[].

Configuration settings are stored in <map/> element which contains list of <entry/> elements. If there are multiple values for a parameter they are stored as a list of <item> elements.

Example 2:

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

Configuration settings can be organised hierarchically using <node> elements:

Example 3:

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

Detailed description for all possible settings is split to per-component chapter. Please look for particular component description for details.

Old way - editing configuration file manually

Options you most likely have to change at deployment time are:

1. Admin accounts - account names where all admin messages are sent.
2. Hostnames - real and virtual hostnames your server has to serve for.
3. Logs - setting related to log file location and how much information should be logged there.

Please let me know if you think more options should be described here.

At the moment the only way to change configuration is to manually edit XML config file. So be prepared for tough times. The good news it that more user friendly interfaces are scheduled for next release. And it will be also reconfigure server at runtime without need to restart service.

Admin accounts

This is the most likely thing to change after you install server and generate default configuration. Actually it is also the easiest option to customize.

Open tigase-config.xml in you favorite text editor and search for string: "admins". You should find section looking like this:

   <entry type="String[]" key="admins">
    <item value="admin%40your.hostname.com"/>
    <item value="admin%40localhost"/>
   </entry>

Characters "%40" stand for '@'. So assuming you have just 1 admin account on your installation which is: "frank@jabber.example.com" you need to replace above code with:

   <entry type="String[]" key="admins">
    <item value="frank%40jabber.example.com"/>
   </entry>

And yes, you can just remove second entry with admin account: "admin@localhost" unless you really want to keep it. Be aware though all system messages will be sent to ALL admin accounts.

Well, if the account does not exists the message is discarded and a warning is be printed in log file. Again, read it again, the previous sentence...

It means that the admin account has to be also created in normal way on the Jabber server. Just register it using your Jabber client. The admin accounts setting works just as a forward instruction. So as a result all system and admin messages are forwarded to all admin accounts if they exist.

Obviously you can have admin accounts as many as you like:

   <entry type="String[]" key="admins">
    <item value="frank%40jabber.example.com"/>
    <item value="lucy%40jabber.example.com"/>
    <item value="mark%40jabber.example.com"/>
    <item value="brenda%40jabber.example.com"/>
    <item value="luck%40jabber.example.com"/>
   </entry>

Hostnames

This one might be a little bit more tricky than previous as hostnames setting has to be changed in a few places. Don't ask why now as this is "Short configuration guide", you remember. Here we focus on how not on why.

You have to search configuration file for string "hostnames". There are more than one such sections and you have to find ALL sections looking like:

   <entry type="String[]" key="hostnames">
    <item value="your.hostname.com"/>
    <item value="localhost"/>
   </entry>

It may also look like:

   <entry type="String[]" key="hostnames">
    <item value="localhost"/>
   </entry>

Depending how successful was mechanism for automatic hostname detection. It of course does not depends on your luck. It depends on network configuration on your server.

The first form is more useful as it includes also hostname recognized in network environment. If it is correct then you can just leave it as it is. If it is incorrect you have to change it. Please remember, if you want your server to be able to communicate with other Jabber/XMPP servers the hostname you put there must resolve in DNS to your Jabber server machine IP address. In other words. If you try to connect from the Internet to machine with this hostname the connection should reach your Jabber server.

And remember your Jabber server users' JIDs (Jabber IDs) can include only those hostnames which are included in the configuration. So for our case you can use only JIDs: "user2@your.hostname.com", "user1@your.hostname.com" and so on.

If you server have more Internet addresses (virtual domains) assigned to it your Jabber server can use them all. So your configuration may look like:

   <entry type="String[]" key="hostnames">
    <item value="your.hostname.com"/>
    <item value="clien1.hostname.com"/>
    <item value="another.hostname.com"/>
    <item value="jabber.sample-domain.com"/>
    <item value="jabber.some-project.org"/>
    <item value="localhost"/>
   </entry>

In such case users' JIDs on your Jabber server may include any of defined above domains like: "user1@your.hostname.com", "user1@clien1.hostname.com", "user1@jabber.sample-domain.com". Each of these 3 sample JIDs refer to different user account.

Your server will accept connections only for domains defined in configuration file.

In majority cases it does not matter whether you leave "localhost" or remove it. It is sometimes better to leave it though. So if you are not sure if you can remove it in your environment just leave it as is.

Logs

Logging mechanism is very flexible in Tigase server. You can adjust separate logging level for each single component. You can also direct loggin to many different destinations like console, file, network socket and so on. Unfortunately it also mean it is a bit complex. The general idea however is quite simple so once you understand it it shouldn't be difficult for you anymore. This guide however describes logging very briefly. Loot at full configuration documentation for detailed explanation.

In standard sever configuration you usually want to turn off all logging to console and all warning and more serious notices directed to log file. Let's say logs will be written to /var/log/tigase-server.log which shouldn't get bigger than 10MB and 5 old logs will be preserved. Here are instructions how to set options.

Open tigase-config.xml in you favorite text editor and search for string: "logging". You should find section looking like this:

  <node name="logging">
   <map>
    <entry value="FINE" type="String" key=".level"/>
    <entry value="java.util.logging.ConsoleHandler+java.util.logging.FileHandler" type="String" key="handlers"/>
    <entry value="tigase.util.LogFormatter" type="String" key="java.util.logging.ConsoleHandler.formatter"/>
    <entry value="WARNING" type="String" key="java.util.logging.ConsoleHandler.level"/>
    <entry value="true" type="String" key="java.util.logging.FileHandler.append"/>
    <entry value="5" type="String" key="java.util.logging.FileHandler.count"/>
    <entry value="tigase.util.LogFormatter" type="String" key="java.util.logging.FileHandler.formatter"/>
    <entry value="ALL" type="String" key="java.util.logging.FileHandler.level"/>
    <entry value="100000" type="String" key="java.util.logging.FileHandler.limit"/>
    <entry value="logs%2Ftigase.log" type="String" key="java.util.logging.FileHandler.pattern"/>
    <entry value="true" type="String" key="tigase.useParentHandlers"/>
   </map>
  </node>

Assuming we make this guide easy and strightforward let me show how this section should look like after modification. So you could just copy and paste it to your config file without going into details. After the configuration code I will briefly explain what each line means so you should be able to further adjust settings for your needs.

  <node name="logging">
   <map>
    <entry value="WARNING" type="String" key=".level"/>
    <entry value="java.util.logging.ConsoleHandler+java.util.logging.FileHandler" type="String" key="handlers"/>
    <entry value="tigase.util.LogFormatter" type="String" key="java.util.logging.ConsoleHandler.formatter"/>
    <entry value="tigase.util.LogFormatter" type="String" key="java.util.logging.FileHandler.formatter"/>
    <entry value="OFF" type="String" key="java.util.logging.ConsoleHandler.level"/>
    <entry value="true" type="String" key="java.util.logging.FileHandler.append"/>
    <entry value="5" type="String" key="java.util.logging.FileHandler.count"/>
    <entry value="ALL" type="String" key="java.util.logging.FileHandler.level"/>
    <entry value="10000000" type="String" key="java.util.logging.FileHandler.limit"/>
    <entry value="%2Fvar%2Flog%2Ftigase-server.log" type="String" key="java.util.logging.FileHandler.pattern"/>
    <entry value="true" type="String" key="tigase.useParentHandlers"/>
   </map>
  </node>

Each line explained:

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

Effectively we set WARNING level for all possible logs for all possible components. So more detailed logging information will be discarded. All possible log levels are: OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL.

<entry value="java.util.logging.ConsoleHandler+java.util.logging.FileHandler" type="String" key="handlers"/>

We set 2 handlers for logging information: console and file handler. As we are going to turn off logging to console we could remove all configuration settings for console handler as well. It would simplify configuration file. I don't recommend it though. If there are any problems with your installation switching console logging on might be very helpful and if you remove these settings from config file it may be difficult to bring them back. Hm... maybe not with such excellent documentation.... ;-)

<entry value="tigase.util.LogFormatter" type="String" key="java.util.logging.ConsoleHandler.formatter"/>
<entry value="tigase.util.LogFormatter" type="String" key="java.util.logging.FileHandler.formatter"/>

We set here log formatter for console and file handler. Standard Java handlers print each log message in 2 lines. Tigase formatter prints all logging info in 1 line which make it much easier to filter logs by log type, logging component or log level or whatever you wish. You can just use simple sed command and that's it.

<entry value="OFF" type="String" key="java.util.logging.ConsoleHandler.level"/>

Here we just switch console handler off. To switch it on back set any different level from the list above.

<entry value="true" type="String" key="java.util.logging.FileHandler.append"/>

This settings is to controll whether we want to append logs into old log file or we want to create new log file (removing old content) each time server is restarted.

<entry value="5" type="String" key="java.util.logging.FileHandler.count"/>

Sets number of old log files to preserve to 5.

<entry value="ALL" type="String" key="java.util.logging.FileHandler.level"/>

This line sets the logging level for file handler. Here we set that we want all possible logs to be written to the file. The global level setting however says that only WARNING logs will be generated. So if you want to have more detailed logs you need to adjust global logging level.

<entry value="10000000" type="String" key="java.util.logging.FileHandler.limit"/>

Log file maximum size set to 10MB. After reaching this size the log file is closed and new file is created.

<entry value="%2Fvar%2Flog%2Ftigase-server.log" type="String" key="java.util.logging.FileHandler.pattern"/>

Location of the log file and file name: /var/log/tigase-server.log. Please note %2F instead of '/' character.

<entry value="true" type="String" key="tigase.useParentHandlers"/>

This setting requires going into more details so it is explained in comprehensive configuration guide.

Configuring the Tigase server to load a component

A detailed description of all the configuration options is in the init.properties guide where you can also find information described below and much more. Purpose of this document however is to give you a quite and brief information how to load a component into the Tigase server without need to dig through all the details.

I will show how to load 2 components into the Tigase server using configuration in the init.properties file: MUC and PubSub. Please remember, every time you change something in the init.properties file you have to remove the XML configuration file in order to force the server to regenerate the main configuration which is stored in XML file.

The first thing you need is the component implementation. Component implementation is a class or set of classes extending tigase.server.AbstractMessageReceiver. What you need to do is just putting the jar file in the libs/ directory in the Tigase server installation. Then the Tigase server will find all classes automatically at the startup time.

Next step is to tell the server what components to load, how to name them and optionally give some extra parameters. To do so please open the init.properties file you use in your installation. It might be init-mysql.properties or init-pgsql.properties or even your own properties file.

Let's say you want to add just PubSub for now. All you need to do is adding just 2 lines to the properties file:

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

 They mean: the first component name is 'pubsub' and the main class for this component is: 'tigase.pubsub.PubSubClusterComponent. It doesn't really matter what the component name is the only requirement is that it must be unique among other components names. It does also help to give it a name which means something thus 'pubsub' is a good name for a 'PubSub' component but it would be a bad name for the 'MUC' component.

We can of course add more components even PubSub components to the same server. Each of them would need to have a different name then. For example:

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

Which is needed in really rare cases.

Normally, however we want to load few different components like PubSub, MUC, MSN Transport and so on.... Therefore instead of the above second PubSub we can load the MUC component:

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

Again! Don't forget to remove your XML config file before restarting the server.

Custom authentication connectors

Tigase server offers you quite a few authentication connectors which allow you to connect to almost any SQL database for user authentication data and share user accounts between the XMPP server and any different system. This feature makes it possible to integrate the Tigase server with other systems without any development effort and without any coding.

This article presents configuration options available to the administrator and describe how to set the Tigase server up to use user accounts data from a different database.

The first thing to know is that the Tigase server always opens 2 separate connections to the database. One connection is for user login data and another is for all other user data like the user roster, vCard, private data storage, privacy lists and so on...

In this article we still assume that the Tigase server keeps user data in it's own database and only login data are retrieved from the external database.

At the moment the Tigase server offers following authentication connectors:

• 'mysql', 'pgsql', 'derby' - standard authentication connector used to load user login data from the main user database used by the Tigase server. In fact the same physical implementation is used for all JDBC databases.
• 'drupal' - is the authentication connector used to integrate the Tigase server with Drupal CMS.
• 'libresource' - is the authentication connector used to integrate the Tigase server with Libresource Collaboration platform.
• 'tigase-auth' - is the authentication connector which can be used with any database. It executes stored procedures to perform all actions. Therefore it is a very convenient way to integrate the server with an external database if you don't want to expose the database structure. You just have to provide a set of stored procedures in the database. While implementing all stored procedures expected by the server might be a bit of work it allows you to hide the database structure and change the SP implementation at any time. You can add more actions on user login/logout without restarting or touching the server. And the configuration on the server side is very simple. For detailed description of this implementation please refer to Tigase Auth documentation. 
• 'tigase-custom' - is the authentication connector which can be used with any database. Unlike the 'tigase-auth' connector it allows you to define SQL queries in the configuration file. The advantage of this implementation is that you don't have to touch your database. You can use either simple plain SQL queries or stored procedures. The configuration is more difficult as you have to enter carefully all SQL queries in the config file and changing the query usually involves restarting the server. For more details about this implementation and all configuration parameters please refer to Tigase Custom Auth documentation.

As always the simplest way to configure the server is through the init.properties file. In the article describing this file you can find long list with all available options and all details how to handle it. For the authentication connector setup however we only need 2 options:

• '--auth-db = connector'
• '--auth-db-uri = database connection url'

If you happen to keep the user data in the same database as user authentication data you can even skip the second parameter as Tigase automatically assumes settings from the '--user-db-uri' it '--auth-db-uri' is missing.

'--auth-db-uri' stored a standard JDBC connection URL and is exactly the same as for all other settings. For example if you store authentication data in the 'drupal' database on 'localhost' the URL might look like:

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

'--auth-db' stored just a connector name or connector implementation class. For convenience the Tigase has predefined short names for the most common connectors but you can always use the class name if you know it. And you have to use a class name if you want to attach your own authentication connector. The following 2 settings are equal:

--auth-db = tigase-auth

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

In the same exact way you can setup connector for any different database type:

--auth-db = drupal

--auth-db = tigase-custom

You can normally skip configuring connectors for the default Tigase database format: 'mysql', 'pgsql' and 'derby' as they are applied automatically if the parameter is missing.

One more important thing to know is that you also have to modify '--user-db-uri' if you use a custom authentication connector. This is because if you retrieve user login data from the external database this external database is usually managed by external system. User accounts are added without notifying the Tigase server. Then, when the user logins and tries to retrieve the user roster the server can not find such a user in the roster database.

To keep user accounts in sync between authentication database and the main user database you have to add following option to the end of the database connection URL: 'autoCreateUser=true'.

For example:

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

If you are interested in even further customize you authentication connector by writing your own queries or stored procedures please have a look at 2 following guides: Tigase Auth guide and Tigase Custom Auth guide.

init.properties

init.properties is a little bit extended version of the Java properties file with (key, value) pairs.

Comment line has it's first non-white space ASCII character either '#' or '!'. 

The key starts with first non-white space ASCII character and ends on either first white space ASCII character or either of '=' or ':'. Therefore if your key contains any of '=', ':' or white space characters you have to escape them with backslash '\': \: or \=.

All of examples below specify 'vhosts' as a key and 'test-a, test-b, test-c' as a value:

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

Normally you can just copy any property from the XML file to the init.properties file and assign other than a default value which will be used the next time XML file is generated. Let's say we have following XML file section:

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

To set the default value for this parameters in the init.properties file you need to assign a value to the key. The key consists of the component name, all node names and the key: 'bosh/5280/tls/allow-invalid-certs' and the value is simply 'false'. So in your init.properties file you simply put following line:

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

If you look closer in inside the XML file you can see that each parameter has a 'key', 'value' and a 'type'. If you put the parameter in the init.properties file you must specify the type of the parameter as well. Otherwise the property won't be loaded. The default type is 'String' therefore for string properties you don't have to specify the type. For all others the type must be set. The type is set by appending [T] at the end of the key name where 'T' indicates the type. Possible types are:

• [S] (or nothing) - Characters string: 'abcdef'
• [s] - String array: 'abcdef, ghaijk, lmnopq'
• [B] - Boolean: 'true' or 'false'
• [b] - Boolean array: 'true, true, false'
• [L] - Long number: 1234567890
• [l] - Long array: '12334, 45435, 45645'
• [I] - Integer number: 123456
• [i] - Integer array: '123, 456, 678'

Let's say we want to set some timeout which is a long type property to value 60:

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

Except the XML parameters you can inject during the configuration generation time there is a bunch of parameters which have broader meaning than just one property. Some of them affect many configuration settings or can generate whole sections in the XML file. Most of them starts with '--' - double hyphen. Here is a list of all those parameters with description:

• 'config-type = --gen-config-def' - probably the only such a property not starting with double hyphen. It sets the server type and determines what components are included in the generated XML file. Possible values are listed below:
  • '--gen-config-all' - creating configuration file with all available components. That is: session manager, client-to-server connection manager, server-to-server connection manager, one external component connection manager, stanza sender and stanza receiver.
  • '--gen-config-def' - creating default configuration file. That is configuration which is most likely needed for a typical installation. Components included in configuration are: session manager, client-to-server connection manager and server-to-server connection manager.
  • '--gen-config-sm' - creating configuration for instance with session manager and external component only. This is useful for distributed installation where you want to have session manager installed on separate machine and components managing network connections on different machines (one or more). Components included in configuration are: 'sm' and 'ext2s'.
  • '--gen-config-cs' - creating configuration for instance with components managing network connections. This is useful for distributed installation where you want to have session manager installed on separate machine and components managing network connections on different machines (one or more). Components included in configuration are: 'c2s', 's2s', 'ext2s'.
• '--user-db = db-type' - where 'db-type' can be one of possible values: mysql, pgsql, xml or the class name. For SQL database this is normally: tigase.db.jdbc.JDBCRepository.
• '--user-db-uri = connection-uri' - where 'connection-uri' is a full resource uri for user repository data source. If you skip this parameter default value is used depending on database type you selected:
  • jdbc:mysql://localhost/tigase?user=root&password=mypass
  • jdbc:postgresql://localhost/tigase?user=tigase
  • user-repository.xml
• '--auth-db = db-type' - where 'db-type' can be one of possible values: mysql, pgsql, xml, drupal, libresource, tigase-auth and tigase-custom (If omitted 'user-db' settings are used.) or the class name. For SQL database this is normally: tigase.db.jdbc.JDBCRepository.
• '--auth-db-uri = connection-uri' - where 'connection-uri' is a full resource uri for user repository data source. (If omitted 'user-db-uri' settings are used.)
• '--ext-comp = connection-string' - possible values: connection string 'localdomain,remotedomain,port,passwd,(plain|ssl),(accept|connect),routing'
  Note: It is also possible to generate configuration for many external components. To do so use '--ext-comp_1 parameters', '--ext-comp_2 parameters' and so on...
• '--virt-hosts = virtual-hosts-list' - possible values: list of virtual domains to support 'domain1,domain2'. This option causes to use virtual hosts given here instead of default/automatically detected host names.
• '--admins = admin-accounts-list' - specifies a list of administrator accounts. Possible values: list of admin accounts: 'user1@domain,user2@domain2'
• '--trusted = trusted-accounts-list' - specifies a list of accounts which are considered as trusted, thus can perform some specific actions on the server. They can execute some commands, send a broadcast message, set MOTD and so on. The configuration is similar to '--adimins' setting.
• '--test' - this parameter informs that config is generated for test instance, which means that all loggings are turned off
• '--debug = tigase-package' - you can turn on debugs log for selected tigase package. For example if you want to turn debug logs on for package: tigase.server then you have to put parameter: '--debug server'. If you have any problems with your server the best way to get help from me is to generate configuration with '--debug = server' and run the server. Then from the logs/tigase-console.log log file I can get all information I need to give you a help. More details about server logging and adjusting logging level is described in article Debugging Tigase.
• '--comp-name-1 = name' - is used to assign name 'name' to the non-standard component which is loaded by the server. It is normally used when you want to load component which is not loaded by the 'config-type' you use. Together with '--comp-class-1' it allows you to load any extra component to your server configuration. Of course you can load more than just one component. Just use '--comp-name-2', '--comp-name-3' and so on... Let's say you want to load the MUC component. You can then put give it a name: 'muc' and the setting would look like:
  

  --comp-name-1 = muc

• '--comp-class-1 = class name' - is used to load an extra component to the server. Normally this parameter is used if you want to load a component which is not included in the 'config-type' you use. You can, of course, load more than just one component using parameters: '--comp-class-2', '--comp-class-3' and so on.... Let's say you want to load the MUC component and the class name for the component is: 'tigase.muc.MUCService'. The line in the properties file should look like:
  

  --comp-class-1 = tigase.muc.MUCService

• '--cluster-mode = (true|false)' - sets the cluster mode. The default value is 'false' so you can normally skip the parameter if you don't want the server to run in the cluster mode. You can run the server in the cluster mode even if there is only one node running. The performance impact is insignificant and you have the opportunity to connect mode cluster nodes at any time without restarting the server.
• '--cluster-nodes = list of cluster nodes' - is a comma separated list of the cluster nodes. The node is a full DNS name of the machine running the node. Please note the proper DNS configuration is critical for the cluster to work correctly. Make sure the 'hostname' command returns a full DNS name on each cluster node. Nodes don't have to be in the same network although good network connectivity is also a critical element for an effective cluster performance.
  

  --cluster-nodes=host-a.domain.com,host-b.domain.com,host-c.domain.com

  All cluster nodes must be connected with each other to maintain user session synchronization and exchange packets between users connected to different nodes. Therefore each cluster node opens a 'cluster port' on which it is listening for connections from different cluster nodes. As there is only one connection between each two nodes the Tigase server has to decide which nodes connects and which has to accept the connection. If you put the same list of cluster nodes in the configuration for all nodes this is not a problem. The Tigase server has a way to find it out and void conflicts. If you however want to add a new node later on, without restarting and changing configuration on old nodes there is no way the old nodes will try to establish a connection to the new node they don't know of. To solve this particular case the next parameter is used.

• '--cluster-connect-all = (true|false)' - causes the cluster node to open active connections to all nodes listed in the '--cluster-nodes' configuration property. This property should be used only on the node which is added to the live cluster at later time. Normally this new cluster node is not listed in configuration of the existing cluster nodes. This is why they can not open connections the new node. The new node opens connection to all existing nodes instead. False is the default value and you can skip this option if you  want to have it switched off. 

• '--sm-plugins = list of pluggins' - lists all plugins which should be loaded by the server. Normally you don't have to specify this. Server loads default list of plugins automatically. The default list contains all available plugins. Sometimes however you might want to load only some plugins. Typical use case is when user accounts are managed on your third-party system the Tigase server is integrated with. Then you might not want to allow users to register new accounts via XMPP service. You can then load a list of plugins without the user registration plugin. Another case when you usually have to use this option is when you have your own plugins which replace function of the Tigase default plugins like vCard, roster management, and so on....
• '--max-queue-size = N' - set internal queues maximum size to a specified value. By default the Tigase sets the queue size depending on the maximum available memory to the Tigase server process. It set's 1000 for each 100MB memory assigned for JVM. This is enough for most use cases. If you have, however extremely busy service with Pubsub or MUC component generating huge number of packets (presence or messages) this size should be equal or bigger to the maximum expected number of packets generated by the component in a single request. Otherwise the Tigase may drop packets which it is unable to process.

Startup file for tigase.sh - tigase.conf

Property file name for tigase.sh startup script is a second parameter for the startup script. It can be skipped if environmental variables are set in different place or in different way.

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.
• TIGASE_OPTIONS - additional options for Tigase server program. You can tweak here initial parameters for your environment.

Sample file to run Tigase with PostgreSQL database may look like:

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 "

Please note encoding settings. I have received several requests about encoding problems. JVM by default uses encoding set in operating system environment. XMPP protocol, however uses UTF-8 for all data processing. So the above settings enforces UTF-8 encoding for all operations.

Another significant setting is 'CLASSPATH'. It is intentionally set to empty string. The tigase.sh startup script builds the CLASSPATH on it's own from files found in jars/ and libs/ directories. I advice to set the CLASSPATH to the empty string because the Tigase server scans all available classes to find all components and plugins implementation. If the CLASSPATH contains lots of libraries which are not used anyway it cases long startup time and lots of memory consumption.

Tigase Auth connector

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 Custom Authentication Connectors guide.

To make this connector working you have to prepare your database to offer set of stored procedures for the 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 mysql-schema-4-sp.schema for MySQL database and in postgresql-schema-4-sp.schema file for PostgreSQL database. You can also refer to the tables definition files to see how database is organized in our implementation: mysql-schema-4.sql file for MySQL database and postgresql-schema-4.sql file for PostgreSQL database.

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

• TigUserLoginPlainPw - to perform user authentication. The procedure is always called when the user tries to login to the XMPP server. This is the only procedure which must be implemented and actually must work.
• TigUserLogout - to perform user logout. The procedure is always called when the user logouts or disconnects from the server. This procedure must be implemented but it can be empty and can do nothing. It just needs to exist because Tigase expect it to exist and attempts to call it.

 With these 2 above stored procedures you can only perform user login/logout 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:

• TigAddUserPlainPw - to add a new user account
• TigRemoveUser - to remove existing user account
• TigUpdatePasswordPlainPw - to change a user password for existing account

Tigase Custom Auth connector

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 Custom Authentication Connectors guide.

The basic configuration is very simple:

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

 That's it.

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

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

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 for unknown reason.

Some queries 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.

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

The same query with plain SQL parameters instead:

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

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

• 'conn-valid-query' - Query executing periodically to ensure active connection with the database.

  Takes no arguments.
  Example query: 'select 1'

• 'init-db-query' - Database initialization query which is run after the server is started.

  Takes no arguments.
  Example query: 'update tig_users set online_status = 0'

• 'add-user-query' - Query adding a new user to the database.

  Takes 2 arguments: (user_id (JID), password)
  Example query: 'insert into tig_users (user_id, user_pw) values (?, ?)'

• 'del-user-query' - Removes a user from the database.

  Takes 1 argument: (user_id (JID))
  Example query: 'delete from tig_users where user_id = ?'

• 'get-password-query' - Rertieves user password from the database for given user_id (JID).

  Takes 1 argument: (user_id (JID))
  Example query: 'select user_pw from tig_users where user_id = ?'

• 'update-password-query' - Updates (changes) password for a given user_id (JID).

  Takes 2 arguments: (password, user_id (JID))
  Example query: 'update tig_users set user_pw = ? where user_id = ?'

• 'user-login-query' - Performs user login. Normally used when there is a special SP used for this purpose. This is an alternative way to a method requiring retrieving user password. Therefore at least one of those queries must be defined: user-login-query or get-password-query.

  If both queries are defined then user-login-query is used. Normally this method should be only used with plain text password authentication or sasl-plain.

  The Tigase server expects a result set with user_id to be returned from the query if login is successful and empty results set if the login is unsuccessful.

  Takes 2 arguments: (user_id (JID), password)
  Example query: 'select user_id from tig_users where (user_id = ?) AND (user_pw = ?)'

• 'user-logout-query' - This query is called when user logs out or disconnects. It can record that event in the database.

  Takes 1 argument: (user_id (JID))
  Example query: 'update tig_users, set online_status = online_status - 1 where user_id = ?'

• 'non-sasl-mechs' - Comma separated list of NON-SASL authentication mechanisms. Possible mechanisms are: password and digest. digest mechanism can work only with get-password-query active and only when password are stored in plain text format in the database.
• 'sasl-mechs' - Comma separated list of SASL authentication mechanisms. Possible mechanisms are all mechanisms supported by Java implementation. The most common are: PLAIN, DIGEST-MD5, CRAM-MD5.
  "Non-PLAIN" mechanisms will work only with the get-password-query active and only when passwords are stored in plain text formay in the database.

Specification for ad-hoc commands used to manage virtual domains

There are 3 ad-hoc commands for virtual domains management in the Tigase server:

1. VHOSTS_RELOAD used to reload virtual domains list from the repository (database).
2. VHOSTS_UPDATE used to add a new virtual domain or update information for existing one.
3. VHOSTS_REMOVE used to remove an existing virtual host from the running server.

Syntax of the commands follows specification described in the XEP-0050. Extra information required to complete the command is carried as data forms described in the XEP-0004.

All commands are accepted by the server only when send by the installation administrator. If the command is sent from any other account <not-authorized /> error is returned. To grant administrator rights to an account you have to set --admins property in the configuration file.

Commands are sent to 'vhost-man' server component and the 'to' attribute of the stanza must contain a full JID of the VHostManager on the server. The full JID consists of the component name: 'vhost-man' and the local domain, that is domain which is already on the list of virtual domains and is active. Assuming 'existing.domain.com' one of domains already activated for the server installation the JID is: 'vhost-man@existing.domain.com'.

Reloading the domains list from the database

In order to reload virtual domains from the permanent repository other than configuration file you have to send VHOSTS_RELOAD ad-hoc command to the VHostManager on the server.

The reload command request is of the form:

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

The server sends a response upon successful completion of the command with current number of virtual domains server by the installation:

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

 If the command is sent from other than admin account the server returns an error:

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

The response doesn't have any special meaning other then informative for the end-user. The client may ignore response as it is sent after the command has been executed.

Adding a new domain or updating existing one

In order to add a new domain or update existing one you have to send an ad-hoc command VHOSTS_UPDATE with at least domain name in the command data form. You can also specify whether the domain is enabled or disabled but this is optional. Future releases may allow for setting additional parameters for the domain: maximum number of user accounts for this domain, anonymous login enabled/disabled for the domain, registration via XMPP enabled/disabled for this domain and some more parameters not specified yet.

The domain add/update command request is of the form:

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

Please note! Character case in the command field variable names does matter.

Upon successful completion of the command the server sends a response back to the client with information of the existing number of virtual hosts on the server:

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

Removing a virtual domain from the server

In order to remove a virtual domain you have to send VHOSTS_REMOVE command to the server with the domain name.

The domain remove command is sent by the client:

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

Upon successful completion of the command the server sends a response back to the client with information of the existing number of virtual hosts on the server:

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

Configuration wizards

From the build #247 you can use configuration generators to easily and quickly create configuration file for even complex case.

Tigase configuration is not too easy to understand and maintain. Even with current command line tools you still have to know what the all options are for.

To make it easier for average administrators or people who run the server for the first time or even for those who want to quickly test Tigase server in different scenarios configuration generators have been created. For each generator you can have also a few extra options which allows you to create configuration which you don't need to change for some time.

A few definitions first to make it easier to read the rest:

• sm - session manager component.
• c2s - client connection manager component
• s2s - server connection manager component
• ext2s - external component connection manager
• ssender - StanzaSender component

The are 4 generators currently available:

1. --gen-config-all - creating configuration file with all available components. That is: sm, c2s, s2s, ext2s, ssender.
2. --gen-config-default - creating default configuration file. That is configuration which is most likely needed for basic installation. Components included in configuration are: sm, c2s, s2s.
3. --gen-config-sm - creating configuration for instance with session manager and external component only. This is useful for distributed installation where you want to have session manager installed on separate machine and components managing network connections on different machines (one or more). Components included in configuration are: sm and ext2s.
4. --gen-config-cs - creating configuration for instance with components managing network connections. This is useful for distributed installation where you want to have session manager installed on separate machine and components managing network connections on different machines (one or more). Components included in configuration are: c2s, s2s, ext2s.