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'.
  • '--gen-config-comp' - generating a configuration with only one component - component managing external components connection, either XEP-0114 or XEP-0225. This is used to deploy a Tigase instance as external component connecting to the main server. You have to add more components handled by this instance, usually these are MUC, PubSub or any other custom components. You have to refer to description for --comp-name-1 and --comp-class-1 properties to learn how to add components to the Tigase instance. You also have to configure the external component connection, domain name, password, port, etc... Please look for a description for --external and --bind-ext-hostnames properties.
• '--admins = admin-accounts-list' - specifies a list of administrator accounts. Possible values: list of admin accounts: 'user1@domain,user2@domain2'
• '--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.)
• '--bind-ext-hostnames = comma separated list of domains (ver. 5.x)' - is a list of domains to be bound to the external component connection. Let's say we have a Tigase instance with only MUC and PubSub components loaded and we want to connect this instance to the main server via external component protocol. Using --external property we can define a domain (maybe muc.devel.tigase.org), password, TCP/IP port, remote host address, connection type, etc.... This would make one of our component (MUC) visible on the remote server.
  To make visible the second component (PubSub) we would need to open another connection with the domain name (pubsub.devel.tigase.org) for the another component. Of course the second connection is redundant as all communication could go through a single connection. This is what this property is used. In our example with 2 components you can just put the 'pubsub.deve.tigase.org' domain as a value to this property and it will bind the second domain to a single connection on top of the domain which has been authenticated during protocol handshaking.
• '--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. 
• '--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.

• '--cmpname-ports = list of ports' - is used to set ports list for a connection manager. 'cmpname' is a component name of the connection manager you want to change ports numbers for. 'list of ports' is a comma separated list of ports numbers. For example for the server to server connection manager named s2s the property would like like the example below:
  

  --s2s-ports=5269,5270,5271

• '--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.MUCComponent

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

• '--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.
• '--debug-packages = any-package' - you can turn debugging on for any package not necessarily within tigase packages. Basically you can put here full packages or classes names as comma separated list.
• '--ext-comp = connection-string' - creates a connection over external component protocol - XEP-0114. The connection can be made to/from any XEP-0114 application: IM transort, MUC, PubSub and others. It is also possible to separate Tigase internal components onto separate instances connected via XEP-0114 connections. 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...
• '--extcomp-repo-class = repository-class (ver. 5.x)' - sets a class managing external component repository. There are 3 available now and you can implement and use your own. The 3 available are:
  'tigase.server.ext.CompConfigRepository' which reads settings for external components from configuration only. It works well with ad-hoc commands, you can add, remove and update external component settings but your changes are not saved to any permanent storage.
  'tigase.server.ext.CompDBRepository' which reads settings for external components from configuration and from database. As a database backend it uses UserRepository. It works well with ad-hoc commands and your changes are stored in DB and are loaded after server restart. All data are cached in memory so it doesn't cause a significant load on database. As it uses UserRepository data are stored in a format hard for direct modifications in database and because of caching in memory all the data it is also not a good choice in cluster environment as changes made on one node are not quickly propagated to other nodes - a reload ad-hoc command must be called on all nodes.
  'tigase.server.ext.CompSQLRepository' which reads initial settings from configuration and also stores data in SQL database. It automatically creates a dedicated DB table with a simple structure suitable for direct modifications with SQL command. It also doesn't cache any data. External component details are read from DB on demand when the component tries to authenticate. As it doesn't cache any data, each authentication request requires DB access therefore it may put some load on DB. On the other hand it allows for easy external components management from a separate application connecting directly to DB and all changes are instantly picked up by all cluster nodes.
• '--external = parameters-string (ver. 5.x)' - defines parameters for external component connections.
  The component is loaded the same way as all other Tigase components. In your init.properties file you need to add 2 lines:

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

  This will load the component with an empty configuration and is practically useless. You have to tell the component on what port to listen (or on what port to connect) and external domains list with passwords.
  As a value you have to put comma separated list of external domains settings. Each domain settings consist of a few, colon separated parameters. For example:
  --external = muc1.devel.tigase.org:passwd1,muc2.devel.tigase.org:passwd2
  This sets passwords for 2 external domains but does not say anything about port number or about connection. The above list is a simplified syntax. The full syntax looks like this:
  --external = muc1.devel.tigase.org:passwd1:listen:5270
  or
  --external = muc1.devel.tigase.org:passwd1:connect:5270:devel.tigase.org:accept
  Meaning of each colon separated part:
  external component domain
  : password for this domain
  : connection type - 'listen' for incoming connections or 'connect' for the remote server
  : port number for the TCP/IP connection (listening on or connecting to)
  : if the connection type is 'connect' then here should the remote hostname address to connect to can be skipped for 'listen' connection type
  : if the connection type is 'connect' then here is protocol to use - 'accept' for XEP-0114,
  'client' for XEP-0225, possible others in the future, can be skipped for 'listen' connection type.
  Only 2 first parts are mandatory, the rest is optional. The simplified form is used to provide a list of domains:password elements for external components connections.
  The settings on the server side may most likely looks like this:
  --external=muc1.devel.tigase.org:passwd1:listen:5270,muc2.devel.tigase.org:passwd2,muc3.devel.tigase.org:passwd3
  It specifies 3 domains with passwords and one TCP/IP port to listen to. On the other hand you can specify a configuration which would establish connection to the server:
  --external = muc1.devel.tigase.org:passwd1:connect:5270:devel.tigase.org:accept
  We use one of the domains configured on the server side, the same port number and
  the server address. (Assuming the main server works at devel.tigase.org address)

• '--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.
• '--monitoring=jmx:9050,http:9080,snmp:9060 (ver. 4.x)' - please refer to the monitoring guide for details.
• '--net-buff-high-throughput = N (ver. 4.3.x)' - sets the network buffer for high traffic connections like s2s or connections between cluster nodes. The default is 64k and is optimal for medium traffic websites. If your cluster installation can not cope with traffic between nodes try to increase this number.
• '--net-buff-standard = N (ver. 4.3.x)' - sets the network buffer for standard (usually c2s) connections, default value is 2k and is optimal for most of cases.
• '--nonpriority-queue=false (ver. 5.x)' - the property can be used to switch to non-priority queues usage in the Tigase server (value set to 'true'). Using non-priority queues prevents packets reordering. By default the Tigase uses priority queues which means that packets with highest priority may take over packets with lower priority (presence updates) which may result in packets arriving in wrong order.
• '--script-dir=scripts/admin (ver. 4.3.x)' - sets the directory where all administrator scripts for ad-hoc command are stored.
• '--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....
  To prevent the plugin from loading add '-' before its ID, to load the plugin add '+' (which is optional). For example, following settings would switch user registration off, while adding a new plugin: 'your-plugin':

  --sm-plugins=-jabber:iq:register,+your-plugin

  There is more to this. Each plugin is running in one or more separate threads. Most plugins which deal with database have number of threads equal to number of CPUs or CPU cores. Sometimes it is not enough. If the database is slow or there is a specific kind of traffic at high level you might want to adjust number of threads for the plugin. To set a different from standard number of threads, just add '=N' where N is the number of threads you want. Above example has been modified to assign 8 threads for your plugin and 16 threads for authentication plugin:

  --sm-plugins=-jabber:iq:register,+your-plugin=8,jabber:iq:auth=16

• '--ssl-container-class=tigase.extras.io.PEMSSLContextContainer' - the option allows you to specify a class implementing storage for SSL/TLS certificates. The class presented in the example to this description allows for loading certificates from PEM files which is a common storage used on many systems. The default implementation uses Java Keystore.
• '--stringprep-processor=simple (ver. 5.x)' - Sets the stringprep processor for all JIDs handled by the Tigase server. The default 'simple' implementation uses regular expressions to parse and check the user JID. It does not fulfils the RFC-3920 requirements but also puts much less stress on the server CPU, hence impact on the performance is very low.
  Other possible values are:
  'libidn' - provides full stringprep processing exactly as described in the RFC-3920. It requires lots of CPU power and significantly impacts performance.
  'empty' - doesn't do anything to JIDs. JIDs are accepted in the form they are received. No impact on the performance and doesn't use any CPU. Suitable for use in automated systems where JIDs are generated by some algorithm, hence there is no way incorrect JIDs may enter the system.
• '--test' - this parameter informs that config is generated for test instance, which means that all loggings are turned off
• '--tigase-config-repo-class = tigase.conf.ConfigurationCache (ver. 5.x)' - is a parameter which allows loading different configuration storage engines. The default one, pointed in the example stores configuration in memory only. Other possible are: tigase.conf.ConfigXMLRepository which keeps configuration in the old XML file and tigase.conf.ConfigSQLRepository which stores configuration in SQL database. Please note, in all cases the init.properties file can still be read and works the same way - provides an initial settings for the Tigase runtime.
• '--tigase-config-repo-uri = database connection uri (ver. 5.x)' - is a parameter which allows to provide database connection string for configuration storage engines which keep server settings in database.
• '--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.
• '--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
• '--user-repo-pool-size = N (ver. 4.x)' - sets the connection pool size to the UserRepository.
• '--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.