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.)
• '--auth-repo-pool = tigase.db.UserAuthRepositoryPool (ver. 5.1)' - allows to specify an implementation for the authentication repository connection pool. This is used only if the implementation provided by a default Tigase server package is not sufficient in the particular deployment. The implementation provides a DB (UserAuthRepository to be more specific) connection pool to improve the data access performance. The repository pool can offer data caching for improved performance or any other features necessary.
• '--auth-domain-repo-pool = tigase.db.UserAuthRepositoryMDImpl (ver. 5.1)' - allows specify an implementation for per-domain UserAuthRepository implementation. This is used only if the implementation provided by a default Tigase server package is not sufficient in the particular deployment. The implementation provides a DB (UserAuthRepository to be more specific) connection pool where each connection (UserAuthRepository) handles data for a different DNS domain (VHost). This allows for database (user data) sharding to improve the system performance and better balance the load.
• '--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.
• '--queue-implementation = class name (ver. 5.1)' - sets the Tigase internal queue implementation. You can choose between already available and ready to use or you can create own queue implementation and let the Tigase load it instead of the default one.
  Currently following queue implementations are available:
  1. tigase.util.PriorityQueueRelaxed - specialized priority queue designed to efficiently handle very high load and prevent packets loss for higher priority queues. This means that sometimes, under the system overload packets may arrive out of order in cases when they could have been dropped. Packets loss (drops) can typically happen for the lowest priority packets (presences) under a very high load.
  2. tigase.util.PriorityQueueStrict - specialized priority queue designed to efficiently handle very high load but prefers packet loss over packet reordering. It is suitable for systems with a very high load where the packets order is the critical to proper system functioning. It means that packets of the same priority with the same source and destination address are never reordered. Packets loss (drops) can typically happen for all packets with the same probability, depending which priority queue is overloaded.
  3. tigase.util.NonpriorityQueue - specialized non-priority queue. All packets are stored in a single physical collection, hence they are never reordered. Packets are not prioritized, hence system critical packets may have to wait for low priority packets to be processed. This may impact the server functioning and performance in many cases. Therefore this queue type should be choosen very carefully. Packets of the same type are never reordered. Packets loss (drops) can typically happen for all packets which do not fit into the single queue.
  Please note! Since the packets are processed by plugins in the SessionManager component and each plugin has own thread-pool with own queues packet reordering may happen regardless what queue type you set. The reordering may only happen, however between different packet types. That is 'message' may take over 'iq' packet or 'iq' packet may take over 'presence' packet and so on... This is unpredictable.
• '--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

• '--sm-threads-pool = (default|custom:NN) (ver. 5.1.x)' - the property allows you to fine-tune the SM plugins (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 a different thread pools.
  If you really need or want to preserve the order for packets processed by different plugins then the solution is to use the 'custom' thread pool. In such a case packets processed by all plugins are handled within a single thread pool. This guarantees that the packets are processed and delivered in the exact order they arrive. The number after the colon ':' specifies the thread pool size.
  What about fine-tuning then? Yes, there is an option to fine tune this even further. Let's say you want most of the plugins to be executed within a single thread pool to preserve packet ordering for them, but some, selected plugins can/should execute within separate, own 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. User cannot send or receive anything else before he authenticates anyway. The solution is to specify number of threads for selected plugins in the --sm-plugins property as described above. For example, setting a common thread pool for all plugins but registration and authentication can be done with following configuration:

  --sm-threads-pool=custom:100
  --sm-plugins=jabber:iq:register=8,jabber:iq:auth=16,urn:ietf:params:xml:ns:xmpp-sasl=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 '<strong>simple'</strong> 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:
  <strong>'libidn'</strong> - provides full stringprep processing exactly as described in the RFC-3920. It requires lots of CPU power and significantly impacts performance.
  <strong>'empty'</strong> - 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 = tigase.db.UserRepositoryPool (ver. 5.1)' - allows to specify an implementation for the repository connection pool. This is used only if the implementation provided by a default Tigase server package is not sufficient in the particular deployment. The implementation provides a DB (UserRepository to be more specific) connection pool to improve the data access performance. The repository pool can offer data caching for improved performance or any other features necessary.
• '--user-domain-repo-pool = tigase.db.UserRepositoryMDImpl (ver. 5.1)' - allows specify an implementation for per-domain UserRepository implementation. This is used only if the implementation provided by a default Tigase server package is not sufficient in the particular deployment. The implementation provides a DB (UserRepository to be more specific) connection pool where each connection (UserRepository) handles data for a different DNS domain (VHost). This allows for database (user data) sharding to improve the system performance and better balance the load.
• '--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.