Tigase Administration Guide

Tigase Team <team@tigase.com> v8.2.0-SNAPSHOT, 2020-09-17 :toc: :toclevels: 3 :numbered: :website: http://tigase.net

1. Tigase Release Notes

Welcome to Tigase XMPP Server 8.2.0-SNAPSHOT! This is a feature release for Tigase XMPP Server v8 with a number of fixes and updates.

1.1. Tigase XMPP Server 8.2.0 announcement

Tigase XMPP Server 8.2.0-SNAPSHOT Change notes and announcement

1.1.1. Major Changes

MIX support

Version 8.2.0 brings in MIX support

MIX Works in cluster (with ACS-MIX component, requires licence) and with all database, including MongoDB Add support for storing MIX data in MongoDB

1.1.2. New Minor Features & Behavior Changes

1.2. Previous Releases

1.2.1. Tigase XMPP Server 8.1.0 announcement

Tigase XMPP Server 8.2.0-SNAPSHOT Change notes and announcement

Major Changes
More XMPP extensions

Following XMPP guidelines specified in Compliance Suites a number of extensions was included in this release:

  • XEP-0157: Contact Addresses for XMPP Services (server-995) that can be configured on per VHost basis (server-1015)

  • XEP-0398: User Avatar to vCard-Based Avatars Conversion (server-1017)

  • XEP-0156: Discovering Alternative XMPP Connection Methods - Tigase already supported handling DNS queries and standardised our webservice to XEP-0156 (http-76)

  • XEP-0410: MUC Self-Ping (Schrödinger’s Chat) (muc-122)

  • XEP-0153: vCard-Based Avatars - added support for setting vCard avatar for MUC rooms (muc-112)

  • XEP-0411: Bookmarks Conversion (pubsub-79)

  • XEP-0157: Contact Addresses for XMPP Services (server-995)

Improved connectivity with other servers

SASL-EXTERNAL mechanism was added for server-to-server (federated, s2s) connections greatly improving compliance with XMPP network. It’s possible to use both SASL-EXTERNAL and Diallback depending on support in other servers.

Better security & privacy

When it comes to connectivity, Tigase XMPP Server sported Hardened Mode that adjusted networking security settings (supported protocols, cipher suites and keys' length where applicable). We decided include 3-level configuration option for Hardened Mode (roughly following Mozilla’s SSL Configuration Generator): relaxed, secure (default) and strict and to further eliminate cipher suites that are currently considered insecure.

We also enabled by default our anti-spam plugin and because we like all-things-extensible we created a guide how to create your own pluggable filters for anti-spam-plugin.

Multiple domains (VHosts) support is even better

It was always quite easy to configure and serve multiple domains in Tigase XMPP Server. In this release we made it even better! First of all - we included Default VHost item, which allows configuring global defaults for the installation on the fly without having to change configuration files and restart the instance.

Internally, we introduced VHost Extensions - a mechanism that allows easy addition of configurable options that can be set on per-domain basis.

On top of that we reworked how SSL certificates are handled (especially wildcard ones) and now they are loaded and assigned to correct domain automatically - no need to configure star-certificates manually anymore.

Mobile First

Notifications send to mobile applications via Apple’s and Google’s push servers using Tigase’s PUSH component are now encrypted (#push-25), requires compatible clients)

MUC component now allows users to register permanent nickname, which makes it possible to receive PUSH notifications even if our client disconnects and is offline (#muc-115)

Installation & management

The (web) installer was simplified making setting up and configuring Tigase even easier (#http-78) - now it’s only needed to select desired database, provide it’s details and eventually adjust which components and plugins should be enabled or disabled, but we believe that provided defaults should work well in most of the cases.

After the installation and startup, it’s possible to see basic instance state via web browser either opening /server/ endpoint (#server-1164), or local file from logs/server-info.html) and manage the installation using Admin WebUI, that received slight visual face-lift (#http-90)

Noteworthy
  • Startup time was significantly reduced due to improvements of creating repository pools (#server-1149)

  • Multi-thread, highly concurrent script execution was improved (#server-1154)

  • StreamManagement was available, but in this version we decided to enabled it by default.

  • More places offers support for XEP-0059: Result Set Management - namely PubSub nodes discovery and jabber:iq:serach

  • Publishing Options were added to PubSub (#pubsub-75)

New Minor Features & Behavior Changes
  • server-918: AWS obtain public IP and/or DNS address of the EC2 instance

  • server-985: Add support for SCRAM-SHA-512(-PLUS)

  • spam-8: Enable spam processor by default

  • server-1012: UserDomainFilter.groovy fails to load

  • server-1014: Can’t upgrade from 8.0.0GA to 8.1.0-SNAPSHOT

  • server-798: Limit number of messages that are stored in DB per user within a period of time

  • server-827: Seperate Component-based statistics

  • server-1026: NPE: in JabberIqRegister/EmailConfirmationSender

  • pubsub-82: NPE in RetrieveItemsModule

  • tigaseim-78: IPv6 connectivity issue

  • server-239: OSGi mode - exceptions in logs

  • server-1020: Enable stream management by default

  • pubsub-83: NPE in PublishItemModule

  • pubsub-81: Exception during execution of event: tigase.pubsub.modules.PresenceCollectorModule.PresenceChangeEvent

  • server-1021: NPE: Cannot update BruteForceLocker

  • server-826: UserRepository caches force synchronization even if caching is disabled

  • server-958: Add timeout for opened TCP connections

  • server-1029: Read receipients are not copied via carbons

  • server-1015: Allow configuring XEP-0157: Contact Addresses on per VHost basis

  • pubsub-65: RSM and jabber:search for pubsub discovery

  • server-1030: NPE in VCardTemp when processing initial presence

  • http-72: Change Content-Disposition from attachment to inline

  • server-1045: NPE in DiscoExtensionsForm

  • server-1048: Update parent pom and information about suggested JDK

  • push-23: [JDK12] Can’t establish encrypted connection with Push/FCM

  • server-978: Improve VHost configuration / extending

  • server-1068: Improve LogFormat readability (and maybe performance)

  • server-1070: Improve privacy list loggging

  • server-1071: NPE in IOService.accept

  • server-710: Registration improvements

  • pubsub-79: XEP-0411: Bookmarks Conversion

  • pubsub-75: Add support for Publishing Options

  • server-1017: XEP-0398: User Avatar to vCard-Based Avatars Conversion

  • server-994: Add server support for Entity Capabilities: Stream Feature

  • server-995: XEP-0157: Contact Addresses for XMPP Services

  • http-76: Standardise DNS webservice to XEP-0156

  • server-1109: Add recommended JDK version to documentation

  • push-28: Non-tigase notifications should use high priority (APNS)

  • server-1114: Can’t register on sure.im with StorkIM

  • server-1005: Flatten schema to match versioning document

  • server-1116: account_status is not checked

  • server-1074: Hardened Mode improvements

  • server-1125: StatsDumper.groovy doesn’t work in documentation in 8.x

  • http-85: Pasword resset doesn’t work

  • server-1128: Possible vulnerability in XML parser

  • server-1130: NPE i JabberIqAuth

  • http-84: Configurable resetPassword endpoint hostname

  • server-1129: BOSH timeouts on GET requests

  • prv-436: Conversations compliance - contact developers

  • server-1100: CAAS and WS testers fail to connect to wss://tigase.im:5291

  • server-1047: Add SASL-EXTERNAL on s2s conections

  • server-1103: High priority PUSH notifications are sent for all messages

  • pubsub-93: NPE in CapsChangeEvent

  • server-1137: Don’t require setting JAVA_HOME to start server

  • server-1136: upgrade-schema --help not available

  • utils-19: tigase-utils doesn’t compile with JDK12

  • server-1138: Schema files are not sorted correctly during loading

  • pubsub-98: Resources with emoji chars are causing issues with MySQL backend

  • server-1110: Disabling TLS in VHost configuration doesn’t work

  • server-1078: Don’t send root CA certificate in chain

  • server-1113: Don’t advertise SASL-EXTERNAL if own certificate is not valid

  • http-78: Simplify installer

  • server-1133: Not able to connect via S2S to server with incorrect SSL certificate

  • serverdistribution-2: MUC upgrade not linked correctly in global tigase guide

  • server-1149: Reduce startup time with a lot of database connections

  • server-1148: "ERROR! Component <x> schema version is not loaded in the database or it is old!" during shutdown

  • server-1153: Refactor Credentials related username to credentialId to avoid confussion

  • servers-312: No cluster connection to send a packet

  • server-1154: Multi-thread script execution yields wrong results

  • servers-294: Can’t connect from tigase.im to rsocks.net

  • server-1111: Can’t establish s2s to upload.pouet.ovh

  • server-1143: S2S connectivity issue with OpenFire when SASL external is used

  • servers-309: Issue when connecting to xabber.org: not-authorized: self signed certificate

  • tigaseim-80: Siskin IM push server is not accessible

  • server-1080: After updating certificate via ad-hoc/rest only main certificate is updated

  • http-88: Improve REST documentation

  • http-87: "request accept time exceeded" for every request when using JavaStandaloneHttpServer

  • server-1151: BruteForceLockerExtension (and possibly others) settings are not correctly retrieved

  • http-89: Drop result/error packages received by HTTP-API if no connection present to write response to

  • pubsub-99: Notifications are not sent for +notify from nodes with whitelist access mode

  • pubsub-79: XEP-0411: Bookmarks Conversion

  • server-1157: SCRAM-SHA512 not working

  • server-1159: Improve handling establishing and terminating of the session

  • server-1152: Cleanup warnings from JDBCMsgRepository

  • server-1112: Fallback to diallback if SASL-EXTERNAL fails

  • servers-292: S2S connectivity issues

  • acspubsub-19: REST execution fails on other nodes

  • server-1145: Race condition during storing/loading of offline messages

  • http-90: Add direct links to most useful task in AdminUI main page

  • spam-10: Add documentation for creation of a custom filter

  • server-1163: Review and update SASL Custom Mechanisms and Configuration documentation

  • server-1164: After-installation report - installation status

  • systems-76: Fix issue with StackOverflow due to recursive call in TLSIO; improve debug log

  • server-1082: Sec-WebSocket-Accept not calculated correctly

  • server-1083: Messages sent to full jid are returned with error

  • push-25: Add support for sending encrypted PUSHes

  • server-1085: Improve retrieval of values for all keys in a node in UserRepository

  • muc-115: Add support for MUC and offline message delivery

  • muc-122: XEP-0410: MUC Self-Ping (Schrödinger’s Chat)

  • muc-112: Support for setting vCard avatar for room

  • http-83: Issue with multithreading access to HttpExchange instance

  • httpapijetty-3: Support for HTTP/2

  • httpapijetty-6: Update Jetty version

1.2.2. Tigase XMPP Server 8.0.0 announcement

Tigase XMPP Server 8.0.0 Change notes and announcement

Major Changes
Kernel and beans configuration

Tigase now operates using a Kernel and Beans style of programming. What does this mean for Tigase and You? Good news, really. Tigase XMPP Server is now working as a Kernel program, which will operate on it’s own and handle all the core functionality of the server. Component, and non-essential functionality will now be loaded as Beans. As a user, your experience will not change all that much. However, beans can be loaded and unloaded without having to restart Tigase, meaning that the program will behave more dynamically. This means a smaller footprint on memory on resources when components are not needed, and longer uptimes without having to rest art the program! This also allows for greater flexibility for Tigase XMPP Server to be better customized for unique solutions.

New Configuration File Format

With the change of Tigase to a Kernel and Beans style of programming, we have also changed how the configuration file is managed. Although you will still edit the config.tdsl file like a plaintext file, a new style of formatting will be used known as DSL. Domain Specific Language may add more lines, but is a cleaner format, and provides a more secure configuration design since validation of the configuration is done at the domain level. For more information on this format and how to configure Tigase, visit DSL Configuration Guide.

Cluster Node Shutdown Changes

Starting with Tigase XMPP Server 8.0.0, users connected on clustered nodes will be able use a see-other-host strategy when a node is being shutdown. Note: This may not be compatible with all clients. The Ad-hoc command is designed for a graceful shutdown of cluster nodes as a groovy script Shutdown.groovy. This script also allows for the -timeout setting which will delay shutdown of the node, and alert all users (via a headline message) that the server will be shutdown after a time. User clients that are compatible with the command will then detect other connected clusters and maintain their connections.

If the command is being sent to shut down the whole cluster, no see-other-host implementation will be sent, however timeout settings may still be used.

The script may be activated by an ad-hoc command, or sent using REST from remote or Tigase Admin UI.

Significant cleanup of code and repositories

Multiple changes have been made to the structure and coding for v8, many related to trimming size of repositories and old calls. Some of these improvements are listed here:

  • Empty JavaDocs that do not convey values have been removed.

  • All code is reformatted to be compliant with out codestyle guidelines.

  • Calls to System.out.print*() and printStackTrace() have been removed from code.

  • Depreciated and unused classes have been removed.

BouncyCastle being used for StartTLS

BouncyCastle Crypto API has now been employed to handle StartTLS negotiation. By doing this, Tigase now supports tls-unique within the SCRAM PLUS authentication implementation. This API is may be employed by calling the class in your configuration file:

c2s () {
    sslContextContainer(class: tigase.extras.bcstarttls.BCSSLContextContainer) {}
}

The BouncyCastle classes are included in the dist-max archives.

default-virtual-host property changes

Default virtual hosts property is now able to be configured only as a domain name instead of the list of virtual host domains with options. Additional virtual host domains and their options need to be configured using ad-hoc commands or web AdminUI. Reference Virtual-Hosts Configuration for more details.

All artifacts are signed

Since work began on v8.0.0 Tigase has required that all changes to Tigase XMPP Server and dependencies be signed with known certificates. This version marks the first to be totally signed.

Scaled Down Installation Methods

We have cleaned up installation methods for Tigase and now recommend the use of web-installer method. IzPack installer (files tigase-server-<version>-b<build>.jar installation methods have been removed and will no longer be produced for v8.0.0 and later. Manual installation is still available for those unable to use HTTP or browser access. Visit our Quick Start guide for instructions on these other methods.

Emojis now supported on Tigase XMPP Servers

Emojis are now supported on MySQL databases, however some settings may be need to be changed, although they won’t affect existing databases. Visit this section for details.

XEP-0215 External Service Discovery now supported

Tigase now supports XEP-0215 - External Service Discovery allowing Tigase to discover services that are not available VIA the XMPP Protocol. For setup and configuration information visit External Service Discovery Component documentation.

XEP-0313 Message Archive Management now supported

XEP-0313 - Message Archive Management is now supported by Tigase featuring custom enhancements like full-text search and searching by tags. MAM requires Tigase’s message archive to be enabled in the config.tdsl file, and the schema (XEP-0136 or XEP-0313) must be configured in session manager settings. To turn on MAM, see configuration guide located here.

XEP-0363 HTTP File Upload now supported

XEP-0363 - HTTP File Upload is now supported using Tigase HTTP API component now allowing for a more robust one-to-many file uploading option. Configuration details are available at the HTTP File Upload Component section of documentation.

Startup now uses bootstrapping

Tigase now uses bootstrapping to startup, which will load configuration from config.tdsl file like before. Then Tigase will begin it’s normal operations with the configuration options. All startup functions for Tigase will now run under the bootstrap bean.

CAPTCHA system now available for in-band registration

XEP-0077 In band registration can use Data Forms as an option to process new registrations. Now you can secure these registrations by employing a CAPTCHA solution. By enabling this option you can reduce the number of potential spammers and bots on your server.

Schema changes

Now each component has it’s own schema for databases, they are no longer tied into Tigase XMPP server versions making changes and updates to individual components easier, and may not disrupt all users not using certain components. See the schema update section for more details.

Shrinkable Statistics History

Statistics history can now be automatically made smaller if a systems memory resources are above a certain amount. By default this is enabled and will trigger when over 95% of memory is in use. Half of all existing entries will be removed at this time. The same pattern will continue to halve the available records every time the threshold is met. A hard-set minimum of 5 entries is set, so you will always have the last 5 entries. This setting may be adjusted by adding the following setting to your config.tdsl file and adjusting the integer value:

stats() {
  'stats-high-memory-level' = 95
}
Statistics now available for all modules

For any bean, you may enable statistics by using the following

bean (class) {
  statistics = true
}
Spam Protection

Tigase XMPP Server v8.0.0 now includes some efforts to prevent spam bot accounts from running on servers.

Account Registration Limits Expanded

Account registration limits have been expanded and now you can set separate counters, or configure components individually for their own limits. Visit this section for configuration details.

Accounts created using in-band registration now will use confirmation E-mail

In an effort to create a more secure method for implementing JabberIqRegister Tigase XMPP Server will now require the use of a confirmation E-mail by default in the process. The E-mail must be valid, and accounts will be made into pending status until a user clicks the generated URI in the E-mail and activates the account. This is a plugin and must be enabled in the config.tdsl file by using the following code:

'account-registration-email-validator'() {}
Further Spam prevention

Tigase-spam component is now in dist-max distribution package, and has a number of features described here in this section.

Changes in password storage

Before version 8.0.0, user passwords were stored in plaintext in the user_pw database field within tig_users table, but in plaintext. It was possible to enable storage of the MD5 hash of the password instead, however this limited authentication mechanism SASL PLAIN only. However an MD5 hash of a password is not really a secure method as it is possible to revert this mechanism using rainbow tables.

Therefore, we decided to change this and store only encrypted versions of a password in PBKDF2 form which can be easily used for SCRAM-SHA-1 authentication mechanism or SCRAM-SHA-256. SASL PLAIN mechanism can also use these encrypted passwords.

The storage of encrypted passwords is now enabled by default in v8.0.0 of Tigase.

Dynamic TLS Buffer

Memory Buffer for TLS no longer remains at highest buffer size needed for the server session. Buffer will now free memory during idle connections. Thus drastically improving program footprint.

XEP-305 Quickstart now supported

It’s now possible to establish connection faster due to implementation of XEP-0305: XMPP Quickstart (#1936). Feature is only available for c2s Connection Manager (i.e. connections on port 5222) and needs to be enabled in config.tdsl

c2s () {
    'pipelining' = true
}
Database Timestamps

Timestamps in database will be stored using UTC time.

Config-type properties have changed

Config-type is now configured using DSL format. Visit this section for more information. The names of different config-type properties have changed: default replaces --gen-config-def, --gen=config-all, and --gen-config-default configuration types. session-manager replaces --gen-config-sm. connection-managers replaces --gen-config-cs. component replaces --gen-config-comp. setup - is a new type of config created for initial configuration of Tigase XMPP Server.

Note
Old versions are no longer supported, you HAVE to replace old versions with the new ones manually when upgrading to v8.0.0.
Database Watchdog implemented

It is now possible to set connection testing to databases when connections are idle and customize the frequency with which this is done. Visit this section for more details.

Packet statistics expanded

Packet statistics both retrieved VIA XMPP and during graceful shutdown have now been separated to a per-XMLNS basis. This may be disabled by adding the following line to config.tdsl file:

'detailed-other-statistics' = false
XEP-0016 Behavior changes

XEP states that Privacy lists should be used when no user session exists in addition to when there is. Previously, Tigase would only filter results when retrieving messages, allowing blocked users to store offline messages. This has now been changed to reflect the XEP properly, and messages will be filtered while there is no user session. If however, you wish to use the previous version, where offline messages are cached first and then filtered, you may use the following configuration:

'sess-man' {
    'jabber:iq:privacy' () {
        privacyListOfflineCache (active: true) {
          size = 20000
        }
    }
}

By default, the cache has a limit of 10000 entries, that may be set by using size bean as seen above.

Access Control List has new ACL modifiers

New permissions have been added to ACL including DOMAIN_OWNER and DOMAIN_ADMIN to reduce permissions checking, and add another level of fine-grained permissions. For more details, please see Tigase ACL configuration for more details.

Option to ignore schema-version check added

You can now skip the schema check phase for individual databases. To do this, add the following do the datasource configuration block:

DataSource () {
  default () {
    'schema-management' = false
  }
}

This will do the following:

  • Print a warning during repository startup.

  • Skip schema upgrades for the source.

  • Skip schema destruction for the source.

Protection against brute-force attacks

Version 8.0.0 improves security by preventing brute-force attacks. Feature needs to be explicitly enabled and configured (on per VHost basis). Detailed configuration is described in Brute-force attack prevention (#8160)

New Minor Features & Behavior Changes
  • #611 Support for Message of the Day is now enabled in Tigase XMPP Server and can be administered using XEP-0133 Service Administration.

  • #1569 Re-implemented XEP-0133 Service Administration Scripts 4.3 Disable User and 4.4 Re-enable User.

  • #1449 Monitoring modules now works in OSGi mode.

  • #1706 auto-authorize of presence subscriptions can now be set for individual vhosts.

  • #1968 Added a Proxy Wrapper to handle reconnections to database connection pool to help prevent deadlocking threads.

  • #3511 Mechanism responsible for closing XMPP in SessionManager has been changed to process all packets from TCP connection before closing connection.

  • #3802 Implementation and API of LocalEventBus and ClusteredEventBus has been unified and is now available as EventBus.

  • #3918 Session Establishment Advertisement is now optional, bringing session establishment in line with RFC 6121.

  • #4111 Changed input buffer sizing to use a ratio of 2 to 1 based on input capacity. No longer using a constant value.

  • #4212 Database schema files have been flattened and made for better organization.

  • #4501 CounterDataFileLogger now has an upper limit and will be default be shrunk to 75% if available disk space is 5% or less than 100MB.

  • #4654 PubSub component has been updated and new schema uses UTF-8 encoding when hashing database lookup.

  • #4776 Tigase DbSchemaLoader now prompts for password if one is missing from command line.

  • #4788 Push component added to dist-max archive.

  • #4814 SASL-SCRAM will now be automatically disabled if auth database uses encoded passwords.

  • #4844 External components can now have SSL socket connections assigned to them.

  • #4859 Tigase DbSchemaLoader now can support using SSL when connecting to databases.

  • #4874 Tigase Test Suite has been updated to correspond to all changes for v8.0.0.

  • #4877 In-memory repository implemented for testing ONLY.

  • #4880 Tigase config-type settings have been reduced and changed. See this section for more details.

  • #4908 Limited Ad-hoc execution to admin only within monitor component.

  • #5005 Detailed logging configuration is now available in DSL format. See xref:[customLogging] for more details.

  • #5069 Packet processed statistics now separates results based on XML Namespaces.

  • #5079 Tigase DbSchemaLoader can now process multiple .sql files in one command by using a comma separated list when calling.

  • #5086 Tigase server monitor is loaded after delay to prevent NPE during startup.

  • #5149 StanzaReceiver and StanzaSender Components have been deprecated and are no longer part of Tigase XMPP Server. Related SQL tables xmpp_stanza and short_news have also been removed from schemas.

  • #5150 All TigaseDB tables now use the tig_ prefix.

  • #5214 Check has been added if recipient exists before storing offline messages for local jid.

  • #5293 DbSchemaLoader now will fail execution instead of skipping when encountering missing files.

  • #5379 Server ready detection has been improved in testrunner.sh.

  • #5397 Webhelp Documentation will no longer be built.

  • #5422 Errors with Beans will now result in compact and more readable StackTrace print in console log.

  • #5423 System configuration will now be printed to log file as ConfigHolder.loadConfiguration output.

  • #5425 GetAnyFile and GetConfigFile scripts moved to message-router instead of basic-conf.

  • #5429 Adjusted settings for Dynamic Rostering now can use separate beans for multiple implementations.

  • #5430 BindResource is now set to FINER log level to reduce console output verbosity.

  • #5475 Setting default environment variables is now possible in config.tdsl file using env('env-1', 'def-value') lines. Details available in DSL Configuration section.

  • #5496 Destroy Schema task now added to schema manager.

  • #5583 Error messages now properly sent when offline message storage is full.

  • #5674 All components now use UTC timestamp when interacting with databases.

  • #5800 Better annotation of deprecated code, cleanup and removal code previously marked as deprecated.

  • #5964 Server version is now added to JMX statistics.

  • #5982 Remote JVM debugging configuration added to tigase.conf file, commented by default.

  • #6038 Data Source pool connections are now initialized concurrently instead of one at a time, dropping initializing time.

  • #6103 RosterElement`no longer keeps `XMPPResourceConnection instance as it is cached elsewhere. Removal results in net improvement in memory footprint.

  • #6133 Tigase now checks components against server version to ensure compatibility.

  • #6163 Groovy plugin updated to v2.4.12.

  • #6206 Separated TigaseXMLTools and TigaseUtil packages for better compatibility with JDK v9.

  • #6216 MongoDB Driver now updated to v3.5.0.

  • #6560 tigase anti-spam component now included in tigase dist-max archive.

  • #6821 Improved error reporting when errors from ConfigReader.

  • #6842 DefaultTypesConverter no longer requires case sensitive enums.

  • #7082 ClassUtilBean now handles packet filtering for packets part of Tigase Server but not containing beans, other improvements to mDNS.

  • #7433 SeeOtherHost no longer uses PropertiesBeanConfigurator to parse configuration.

  • #7446 User credentials can now be managed with Ad-hoc commands.

  • #7743 Improved error message when repository is not found.

  • #7773 Ad-hoc commands can now by executed asynchronously.

  • #2341 allow specifying SubscriptionType when adding buddy to avoid calling separately .setBuddySubscription() thus eliminating saving roster twice to database if not needed

Fixes
  • #2750 Multiple artifact and depreciated file cleanup. Massive code cleanup and javadoc cleaning.

  • #3582 Schema files streamlined, and no longer embedded in code.

  • #3611 Fixed TheadExceptionHandler caused by ACS unable to read PubSub schema changes.

  • #3686 Issues with processing XHTML-IM have been fixed, and now render correctly messages with multiple CData items.

  • #3689 Packets returned from CM no longer bear the original senders' jid.

  • #3803 New call RouteEvent has been added to check to list and check events and determine which should be forwarded to other nodes.

  • #3822 Error is now thrown if listener is registered for an event that is not found in EventBus.

  • #3910 Fixed NPE in SessionManager when session is closed during execution of everyMinute method.

  • #3911 Fixed issue of dropping connections during thread load distribution.

  • #4185 Fixed an error where messages would be duplicated on stream resumption due to a counter being reset upon reconnection.

  • #4447 Fixed condition where expired messages in offline store would cause locks.

  • #4547 config.dump file now is fully compatible with init.tdsl file and DSL file formatting.

  • #4672 Fixed UnsupportedOperationException occurring during configuration of WebSocketConnectionClustered.

  • #4776 DBSchemaLoader now asks for user credentials if parameter is missing. Exceptions are no longer thrown if file specified is not found.

  • #4885 client-port-delay-listening no longer causes exception when called.

  • #4973 Changed Message History query to now include a limit when selecting items, preventing an SQLTimeoutException.

  • #5005 Fixed an issue where disabling components would result in server shutdown.

  • #5042 Fixed issue when implementing custom SASL providers, mechanisms and callback handler factories.

  • #5066 Fixed issue initializing databases using MongoDB.

  • #5076 last_login and last_logout values are now properly updated while using SASL SCRAM authentication.

  • #5084 SCRAM now checks to see if account is disabled before retrieving password.

  • #5085 Fixed too many beans implemented error in Monitor Component.

  • #5088 Removed unnecessary SASL request processing after session is closed.

  • #5118 Fixed NPE during query of privacy lists then type is missing.

  • #5303 Fixed beans not being overridden by configuration if they were registered in RegistrarBean or AbstractKernelBasedComponent.

  • #5311 Offline messages are no longer dumped from MongoDB when restarting server.

  • #5394 Loading main Derby schema no longer throws exceptions.

  • #5428 Fixed parsing of v-host per domain limit property.

  • #5450 Server no longer automatically shuts down when default or other db can not be found or accessed.

  • #5458 Fixed potential timeout arising from XMPPIOService::xmppStreamOpened() method.

  • #5480 Fixed issue in Derby DB where obtaining offline messages results in SQLException.

  • #5525 Fixed S2S invalid-namespace error being returned during connection establishment.

  • #5587 Fixed unclosed ResultSet when storing a message to AMP-offline database in Derby causing deadlock.

  • #5645 Added fix for possible NPE when failing to retrieve beans.

  • #5670 config-dump now prints configuration for inactive components and beans to log.

  • #5692 Messages sent with negative priority were being occasionally dropped and not processed to OfflineMessageHandler.

  • #5727 Fixed potential issue with MySQL procedures not being killed properly.

  • #5750 Statistics now filter out zero-value results unless FINEST level is requested.

  • #5831 Fixed occurrence of OutOfMemory error.

  • #5864 Fixed NPE when executing BOSH pre-bind script.

  • #5867 Fixed NPE occurring during configuration dump.

  • #6000 Fixed a few issues with dynamic rosters properly handling presence subscription requests.

  • #6006 Improved configuration file and DB Schema handling.

  • #6041 Fixed potential issue where vhosts DB could be overwritten by vhosts configuration in init.config.

  • #6078 Fixed ClusterConnectionManager to use custom_elements_limit instead of a fixed value.

  • #6080 Fixed Packet Filtering to not filter cluster node information requests.

  • #6083 Fixed clustered mode shutting down server when certain components are disabled.

  • #6135 Tigase now properly enabled selective TLS if not enabled globally.

  • #6140 Fixed issue while sending server welcome message.

  • #6141 Fixed NPE at startup.

  • #6234 Fixed an error where an error message would repeat unnecessarily.

  • #6284 Ad-hoc commands now refresh SSL Certificate, and restart is no longer required.

  • #6293 Server no longer sends no response upon setting empty photo in vCard.

  • #6263 Fixed missing namespaces in responses from adhoc commands.

  • #6400 Added a proper error when max-queue-size is too small and server cannot start.

  • #6408 Fixed an issue where single WebSocket frames contained multiple XML stanzas instead of one per frame.

  • #6411 Main kernel is now called to smooth shutdown. Further, timeout periods are opened up for large instances.

  • #6574 SSL certificate upload handling is now fixed within cluster mode.

  • #6598 Fixed EventBus Registration connection issues between cluster nodes.

  • #6658 Cluster connections no longer potentially keep open connection after cluster is no longer connected or available.

  • #6749 Fixed schema parsing for DerbyDB.

  • #6776 Fixed failing Websocket connections if header contains more than one value.

  • #6875 Fixed an issue where C2S connections could be accepted before SessionManager was initialized.

  • #7037 Fixed error while parsing negative values from config.tdsl file.

  • #7055 Improvements to metaspace use and other memory use tweaks.

  • #7304 Virtual host logs now properly follow log size limits.

  • #7431 AdHoc requests between the same user with different resources are no longer dropped with `NoConnectionIdExecption`error.

  • #7434 Adjusted SeeOtherHotDualIP to use new table name in cluster nodes database.

  • #7491 Stacktraces from CertificateContainer are no longer printed to tigase-console.log, but will be printed to tigase.log.

  • #7687 Fixed an error where connections failed after authentication timeout were marked as active after cleanup.

  • #7747 Fixed ClusterRepoItemEvent serialization issues causing unsupported conversion error in cluster mode.

  • #7495 fix issue with not all logs being obfuscated, added testcase, documentation

  • #8305 fix issue with SeeOtherHostDualIP when using MongoDB

Component Changes
AMP
  • #7301 Tigase AMP component now uses multiple processing threads.

PubSub
  • #5033 PubSub now compatible with using emojis in pubsub items.

  • #5693 Fixed parsing configuration of SessionManager processors.

  • #5766 PubSub now writes to all databases with UTC timestamp.

  • #5953 Fixed presences not being removed from presenceByService collection if client disconnects without <unavailable/> presence being sent.

  • #6176 version changed to PubSub v4.0.0.

  • #7707 Fixed potential NPE in PubSub.

http-api
  • #4873 Support added to display timestamp fields as data, time, and timezone fields.

  • #4876 Implemented using XML repository for new setups, and updated default config to use this.

  • #4888 http-api now is enabled by default.

  • #5209 Updated visual styling of pages hosted by component.

  • #5290 Fixed invalid property name.

  • #5316 Account Registration now can now require and send confirmation E-mails.

  • #5415 Web Setup now checks configuration for message archive conflicts.

  • #5460 MongoDB now supported through web-setup.

  • #5717 Fixed default values of check-boxes in admin UI not being shown.

  • #5950 Supported added for XEP-0363: HTTP File Upload.

  • #6159 Fixed NPE thrown if scripts directory is not present.

  • #6176 version changed to tigase-http-api v2.0.0.

  • #6212 Added mechanism for password changing through HTTP API.

  • #7307 Fixed scripts returning 404 while handling rest/user/ requests even though user exists.

  • #7178 Ad-hoc commands are now categorized in groups for better organization.

  • #7568 Added timeout reading for HTTP request headers, added configurable accept-timeout.

message-archive
  • #4867 fixed issue when changing MA jid.

  • #4888 message-archive is enabled by default.

  • #5033 Update message archive to be compatible with emojis.

  • #5391 Added missing query statement block starts and ends to be compatible with SQL Server.

  • #5604 Modified access to static fields and functions.

  • #5681 Fixed duplication of groupchat messages with different ids by modifying hash algorithm.

  • #6176 version changed to message-archive v2.0.0.

  • #7615 feature-not-implemented response no longer occurs when removing stored messages.

MUC
  • #4888 muc now is enabled by default.

  • #5033 MUC component is now compatible with emojis.

  • #5066 Fixed issues working with MongoDB repository.

  • #5085 Removed invalid annotation parameter values.

  • #5559 Fixed NPE while changing default room configuration.

  • #5666 User may add more than one <item/> elements to query when querying room members.

  • #5715 Welcome messages may now be disabled globally, or in individual room configurations.

  • #5736 Rooms with no subject now return empty <subject/> element, as per XEP-0048 7.2.16.

  • #5813 Fixed NPE during room creation.

  • #6176 version changed to tigase-muc v3.0.0.

  • #6395 Fixed tigase.db.UserNotFoundException during retrieval of MUC user.

  • #6734 Introduced muc#roomconfig_maxresources to allow configuration of max number of resources for a single occupant.

  • #7443 Disabled XEP-0091 by default, added history attribute validation.

socks5 Proxy
  • #2750 Cleanup of code and removal of empty javadocs.

  • #5867 Fixed NPE during configuration dump when component is disabled.

  • #6176 version changed to tigase-socks5 v2.0.0.

stats
  • #5206 Fixed exception causing duplicate error entry.

  • #5728 Fixed MySQLIntegrityConstraintViolationException in upload handler.

  • #6161 Removed usage of classes from javax.xml.ws package for JDKv9 compatibility.

STUN Server
  • #6176 version changed to tigase-stun v2.0.0.

WebSocket
  • #6481 Websocket component has been improved to be more compliant with rfc6455

2. Tigase User Guide

Tigase Team <team@tigase.com> v8.2.0-SNAPSHOT, 2020-09-17

2.1. Jabber/XMPP introduction

2.1.1. Jabber/XMPP is Instant Messaging Technology

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

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

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

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

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

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

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

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

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

2.2. How to Use Tigase Service

2.2.1. This Article Describes How to use tigase.im Service for Instant Communications

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

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

Short instructions:

Usually you just need to enter the user name of the form: user@tigase.im. Your XMPP client should take care of all other things as our service doesn’t need any special settings. If you don’t have an account on tigase.im server yet just tick the option to register new account. That’s it!

Long Instructions:

Good news is that there are many programs to choose from which allow you to communicate through our server. So you can pick up your favorite application or use an existing one that is compatible and start using our service.

All clients presented below support multiple accounts on Jabber servers. What this means is that you can have a few Jabber accounts on different Jabber servers and you can still use just one program to connect to all of them at the same time.

The full list of all known XMPP clients is very long. You can obviously try them all but below is a selection which is recommended by the Tigase team. The selected programs might not be the best choice for you, but these programs have been tested and we can offer help with using them. Here is a list of recommended instant messaging clients:

  • Beagle.im - macOS desktop client developed by Tigase team supporting all the latest and greatest features

  • Tigase Messenger for iOS - lightweight, powerful XMPP client developed by Tigase, Inc. It provides an easy way to start using the XMPP Protocol (formerly known as Jabber) if you’ve never used it before. Veterans of the protocol will find many features here they are familiar with along with enhancements to reduce data use and extend battery life.

  • Tigase Messenger for Android - mobile chat client to use with XMPP services and servers. The totally revamped v3.0 now has new features, a better design, and Google integration. Application supports any XMPP server, from free services like sure.im or Tigase.im, to a server you may host on your own.

  • tigase.im[Tigase.im] - web-based client allowing to easily chat with friends independently of platform.

  • Psi Pure Jabber client. Although it supports only Jabber network it is a very user friendly and comfortable program. It works on most popular operating systems like Linux, MS Windows, and Apple MacOS X.

  • Gajim This is another Jabber only client. Very user friendly and works on most of Linux distributions, FreeBSD, and MS Windows.

  • Pidgin (previously Gaim) This is not just a Jabber client. This type of application is called multicommunicator as apart from Jabber it supports many other instant messaging networks/protocols such as: AIM/ICQ, MSN, Yahoo, Gadu-Gadu, IRC, and a few others. So it is especially convenient if you have friends using other messaging networks. Pidgin works on most Linux distributions, and on MS Windows.

  • Kopete This is a KDE component and although it only works on Linux based system it also supports many of the most popular instant messaging protocols apart from Jabber like: AIM, Gadu-Gadu, ICQ, IRC, MSN, Yahoo.

Install the Jabber client of your choice and set up for a Tigase account:

2.3. Configuration instructions for Psi

2.3.1. Psi - Initial configuration

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

Psi First Run

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

  1. Psi can connect to many Jabber servers at the same time so we have to identify each connection somehow. The first thing to do is assign a name to the connection we just created. As we are going to define connection to tigase.org server let’s just name it: Tigase.

    Psi Add Account

    Note! At the moment you can register an account through the Web site only. This is a single account for both services: The Drupal website and Jabber/XMPP service on the tigase.org domain. If you want to have a Jabber account on the tigase.org server go to the registration page, un-tick "Register new account", and go to the point no 5. You can use guide points 2-4 to register a Jabber account on any other Jabber server.

  2. When you press the Add button you will see next window where you can enter your Jabber account details:

    Psi Empty Account

  3. Invent your user name for the account on Tigase server. Let’s assume your user name is: frank. Jabber ID’s however consist of 2 parts - your user name and server address. Exactly the same as an e-mail address. As you are registering an account on tigase.org server, you will have to enter in this field: frank@tigase.org. Next enter the password of your choice and click the Register button.

    Psi Register Account

  4. On successful registration you will receive a confirmation message and you should see a window like this:

    Register Account Success

    It may happen that somebody earlier registered an account with the same name you’ve selected for yourself. If so, you will receive error message. You will then have to select another user name and try to register again.

  5. After clicking the OK button you will see a window with your connection and account setup. You can stick with default values for now.

    PSI After Registration

    Just click the Save button and this window closes.

  6. Now you have your account configured and ready to use but you are still off-line. You can find out whether you are on-line or off-line by looking at the bottom of main Psi window. There you can see Offline text.

    Click on this Offline text and you will see a list of possible options. Just select Online.

    PSI Connected

    Now you are connected!

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

2.3.2. Short Instructions How to Add Your First Contact

  1. Click on Psi menu - the button next to the Online text. You will see something like this:

    PSI Menu

    From all menu options select the top one - Add a contact:

    PSI Menu add Contact

  2. The next window will display where you can enter your contact details:

    PSI Add User Empty

    You have to know the Jabber ID of the person you want to add to your contact list. Let’s assume, for example, you want to add Tigase server administrator’s Jabber ID to your contact list. So, after you enter these details the window will look like this:

    PSI Add User Filled

    Click the Add button.

  3. Now you will see a confirmation window that a new person has been added to your contact list:

    PSI Kobit Added

    But there is more behind the scenes. Adding a contact to your Roster (contact list) usually means you can see whether the person is online and available to talk or not. The person however, may not wish you to see his presence. So, to make sure the other person accepts you as a friend Psi sent a request to the address you just entered with the question of whether he agrees to show his presence to you.

    You won’t be able to see the users availability until he sends confirmation.

  4. Once the other user sends confirmation back, you will usually receive 2 system events:

    PSI Kobit Auth Received

  5. Click on the contact to see a window with these messages:

    PSI Authorized Window

  6. One message just says you have been authorized by the other user:

    PSI Authorized Window 2

    So you simply click Next to see the second message.

  7. The second message is a bit more interesting. It contains the question of whether you also authorize the other user to see your presence. If you want to accept this request just click Add/Auth.

    PSI Authorized Window 3

  8. Finally main Psi window with your new contact:

    PSI Kobit Added Authorized

Well done!

You are ready to start Jabbering. Good luck.

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

Welcome to the Tigase Administration Guide.

3. About Tigase XMPP Server

Tigase XMPP Server is an Open Source and Free (AGPLv3) Java based server. The goals behind its design and implementation of the server are:

  1. Make the server robust and reliable.

  2. Make the server a secure communication platform.

  3. Make a flexible server which can be applied to different use cases.

  4. Make an extensible server which takes full advantage of XMPP protocol extensibility.

  5. Make the server easy to setup and maintain.

3.1. Robust and reliable

This means that the server can handle many concurrent requests/connections and can run for a long time reliably. The server is designed and implemented to handle millions of simultaneous connections.

It is not enough however to design and implement a high load server and hope it will run well. The main focus of the project is put in into testing. Tests are taken so seriously that a dedicated testing framework has been implemented. All server functions are considered as implemented only when they pass a rigorous testing cycle. The testing cycle consists of 3 fundamental tests:

  1. Functional tests - Checking whether the function works at all.

  2. Performance tests - Checking whether the function performs well enough.

  3. Stability tests - Checking whether the function behaves well in long term run. It must handle hundreds of requests a second in a several hour server run.

3.2. Security

There are a few elements of the security related to XMPP servers: secure data transmissions which is met by the implementation of SSL or TLS protocol, secure user authorization which is met by the implementation of DIGEST or SASL user authorization and secure deployment which is met by component architecture.

Secure deployment Tigase software installation does not impact network security. Companies usually have their networks divided into 2 parts: DMZ which is partially open to the outside world and the Private network which is closed to the outside world.

If the XMPP server is to provide an effective way of communication between company employees regardless if they are in a secure company office or outside (perhaps at a customer site), it needs to accept both internal and external connections. So the natural location for the server deployment is the DMZ. However, this solution has some considerations: each company has normally established network users base and integrated authorization mechanisms. However, that information should be stored outside the DMZ to protect internal security, so how to maintain ease of installation and system security?

Tigase server offers a solution for such a case. With it’s component structure, Tigase can be easily deployed on any number machines and from the user’s point of view it is seen as a one logical XMPP server. In this case we can install a Session Manager module in the private network, and a Client Connection Manager with Server Connection Manager in the DMZ.

Session Manager connects to DMZ and receives all packets from external users. Thus is can securely realize users authorization based on company authorization mechanisms.

3.3. Flexibility

There are many different XMPP server implementations. The most prevalent are:

  • Used as a business communication platform in small and medium companies where the server is not under a heavy load. For such deployments security is a key feature.

  • For huge community websites or internet portal servers is, on the other hand, usually under very heavy load and has to support thousands or millions of simultaneous connections. For such a deployment we need a different level of security as most of the service is open to the public.

  • For very small community deployments or for small home networks the key factor is ease to deploy and maintain.

Architecture based on components provides the ability to run selected modules on separate machines so the server can be easily applied in any scenario.

For simple installation the server generates a config file which can be used straight away with very few modifications or none at all. For complex deployments though, you can tweak configurations to your needs and setup XMPP server on as many physical machines as you need.

3.4. Extensibility

The world changes all the time as does user’s needs. The XMPP protocol has been designed to be extensible to make it easy to add new features and apply it to those different user’s needs. As a result, XMPP is a very effective platform not only for sending messages to other users, it can also be extended for sending instant notifications about events, a useful platform for on-line customer service, voice communication, and other cases where sending information instantly to other people is needed.

Tigase server has been designed to be extensible using a modular architecture. You can easily replace components which do not fulfill your requirements with others better fitting your needs. But that is not all, another factor of extensibility is how easy is to replace or add new extensions. A great deal of focus has been put into the server design API to make it easy for other software developers to create extensions and implement new features.

3.5. Ease of Use

Complex computer networks consisting of many servers with different services are hard to maintain. This requires employing professional staff to operate and maintain the network.

Not all networks are so complex however, most small companies have just a few servers for their needs with services like e-mail and a HTTP server. They might want to add an XMPP server to the collection of their services and don’t want to dedicate resources on setup and maintenance. For such users our default configuration is exactly what they need. If the operating system on the server is well configured, then Tigase should automatically pickup the correct hostname and be ready to operate immediately.

Tigase server is designed and implemented to allow dynamic reconfiguration during runtime so there is no need to restart the server each time you want to change configuration settings.

There are also interfaces and handlers available to make it easy to implement a web user interface for server monitoring and configuring.

3.6. XMPP Supported Extensions

3.6.1. Core Compliance Suite

Table 1. Core Compliance Suite

Support

Specification

Name

Comment

RFC6120

Extensible Messaging and Presence Protocol (XMPP): Core

RFC7622

Extensible Messaging and Presence Protocol (XMPP): Address Format

We support previous version of the specification: RFC6122

RFC7590

Use of Transport Layer Security (TLS) in the Extensible Messaging and Presence Protocol (XMPP)

XEP-0368

SRV records for XMPP over TLS

Requires adding DNS entries pointing to port 5223

XEP-0030

Service Discovery

XEP-0115

Entity Capabilities

XEP-0114

Jabber Component Protocol

XEP-0163

Personal Eventing Protocol

3.6.2. Web Compliance Suite

Table 2. Web Compliance Suite

Support

Specification

Name

Comment

RFC7395

An Extensible Messaging and Presence Protocol (XMPP) Subprotocol for WebSocket

XEP-0206

XMPP Over BOSH

XEP-0124

Bidirectional-streams Over Synchronous HTTP (BOSH)

3.6.3. IM Compliance Suite

Table 3. Web Compliance Suite

Support

Specification

Name

Comment

RFC6120

Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence

XEP-0084

User Avatar

XEP-0153

vCard-Based Avatars

XEP-0054

vcard-temp

XEP-0280

Message Carbons

XEP-0191

Blocking Command

XEP-0045

Multi-User Chat

XEP-0249

Direct MUC Invitations

XEP-0048

Bookmarks

XEP-0223

Persistent Storage of Private Data via PubSub

XEP-0049

Private XML Storage

XEP-0198

Stream Management

Both Session Resumption and Stanza Acknowledgements

XEP-0313

Message Archive Management

3.6.4. Mobile Compliance Suite

Table 4. Web Compliance Suite

Support

Specification

Name

Comment

RFC7395

An Extensible Messaging and Presence Protocol (XMPP) Subprotocol for WebSocket

XEP-0198

Stream Management

Both Session Resumption and Stanza Acknowledgements

XEP-0352

Client State Indication

XEP-0357

Push Notifications

3.6.5. Non-Compliance Suite Extensions

Table 5. Core Compliance Suite

Support

Specification

Name

Comment

XEP-0004

Data Forms

XEP-0008

IQ-Based Avatars

XEP-0012

Last Activity

XEP-0013

Flexible Offline Message Retrieval

XEP-0016

Privacy Lists

XEP-0020

Feature Negotiation

XEP-0022

Message Events

XEP-0047

In-Band Bytestreams

XEP-0050

Ad-Hoc Commands

XEP-0059

Result Set Management

XEP-0060

Publish-Subscribe

XEP-0065

SOCKS5 Bytestreams

XEP-0066

Out of Band Data

XEP-0068

Field Standardization for Data Forms

XEP-0071

XHTML-IM

XEP-0072

SOAP Over XMPP

XEP-0077

In-Band Registration

XEP-0078

Non-SASL Authentication

XEP-0079

Advanced Message Processing

XEP-0080

User Location

XEP-0082

XMPP Date and Time Profiles

XEP-0083

Nested Roster Groups

XEP-0085

Chat State Notifications

XEP-0086

Error Condition Mappings

XEP-0091

Legacy Delayed Delivery

XEP-0092

Software Version

XEP-0096

File Transfer

XEP-0100

Gateway Interaction

XEP-0106

JID Escaping

XEP-0107

User Mood

Server support via Personal Eventing Protocol (XEP-0163)

XEP-0108

User Activity

Server support via Personal Eventing Protocol (XEP-0163)

XEP-0118

User Tune

Server support via Personal Eventing Protocol (XEP-0163)

XEP-0127

Common Alerting Protocol (CAP) Over XMPP

XEP-0128

Service Discovery Extensions

XEP-0131

Stanza Headers and Internet Metadata (SHIM)

XEP-0133

Service Administration

XEP-0136

Message Archiving

XEP-0141

Data Forms Layout

✓footnote:commercial[Requires commercial license]

XEP-0142

Workgroup Queues

XEP-0144

Roster Item Exchange

XEP-0145

Annotations

XEP-0146

Remote Controlling Clients

XEP-0152

Reachability Addresses

XEP-0155

Stanza Session Negotiation

XEP-0156

Discovering Alternative XMPP Connection Methods

Uses DNS records, so will work with Tigase XMPP Server

XEP-0157

Contact Addresses for XMPP Services

XEP-0160

Best Practices for Handling Offline Messages

XEP-0166

Jingle

XEP-0167

Jingle RTP Sessions

XEP-0170

Recommended Order of Stream Feature Negotiation

XEP-0171

Language Translation

XEP-0172

User Nickname

XEP-0174

Serverless Messaging

XEP-0175

Best Practices for Use of SASL ANONYMOUS

XEP-0176

Jingle ICE-UDP Transport Method

XEP-0177

Jingle Raw UDP Transport Method

XEP-0178

Best Practices for Use of SASL EXTERNAL with Certificates

XEP-0179

Jingle IAX Transport Method

XEP-0180

Jingle Video via RTP

XEP-0181

Jingle DTMF

XEP-0184

Message Receipts

XEP-0185

Dialback Key Generation and Validation

XEP-0190

Best Practice for Closing Idle Streams

XEP-0199

XMPP Ping

XEP-0201

Best Practices for Message Threads

XEP-0202

Entity Time

XEP-0203

Delayed Delivery

XEP-0205

Best Practices to Discourage Denial of Service Attacks

XEP-0209

Metacontacts

XEP-0220

Server Dialback

XEP-0224

Attention

XEP-0225

Component Connections

XEP-0226

Message Stanza Profiles

XEP-0231

Bits of Binary

XEP-0234

Jingle File Transfer

XEP-0245

The /me Command

XEP-0246

End-to-End XML Streams

XEP-0247

Jingle XML Streams

XEP-0250

C2C Authentication Using TLS

XEP-0251

Jingle Session Transfer

XEP-0260

Jingle SOCKS5 Bytestreams Transport Method

XEP-0261

Jingle In-Band Bytestreams Transport

XEP-0262

Use of ZRTP in Jingle RTP Sessions

XEP-0277

Microblogging over XMPP

XEP-0292

vCard4 Over XMPP

XEP-0301

In-Band Real Time Text

XEP-0305

XMPP Quickstart

XEP-0323

Internet of Things - Sensor Data

XEP-0324

Internet of Things - Provisioning

XEP-0325

Internet of Things - Control

XEP-0326

Internet of Things - Concentrators

XEP-0333

Chat Markers

XEP-0363

HTTP File Upload

XEP-0387

XMPP Compliance Suites 2018

3.6.6. Full, ordered list of supported RFCs and XEPs:

Support

Specification

Name

Comment

RFC6120

Extensible Messaging and Presence Protocol (XMPP): Core

RFC6120

Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence

RFC7622

Extensible Messaging and Presence Protocol (XMPP): Address Format

We support previous version of the specification: RFC6122

RFC7395

An Extensible Messaging and Presence Protocol (XMPP) Subprotocol for WebSocket

RFC7395

An Extensible Messaging and Presence Protocol (XMPP) Subprotocol for WebSocket

RFC7590

Use of Transport Layer Security (TLS) in the Extensible Messaging and Presence Protocol (XMPP)

XEP-0004

Data Forms

XEP-0008

IQ-Based Avatars

XEP-0012

Last Activity

XEP-0013

Flexible Offline Message Retrieval

XEP-0016

Privacy Lists

XEP-0020

Feature Negotiation

XEP-0022

Message Events

XEP-0030

Service Discovery

XEP-0045

Multi-User Chat

XEP-0047

In-Band Bytestreams

XEP-0048

Bookmarks

XEP-0049

Private XML Storage

XEP-0050

Ad-Hoc Commands

XEP-0054

vcard-temp

XEP-0059

Result Set Management

XEP-0060

Publish-Subscribe

XEP-0065

SOCKS5 Bytestreams

XEP-0066

Out of Band Data

XEP-0068

Field Standardization for Data Forms

XEP-0071

XHTML-IM

XEP-0072

SOAP Over XMPP

XEP-0077

In-Band Registration

XEP-0078

Non-SASL Authentication

XEP-0079

Advanced Message Processing

XEP-0080

User Location

XEP-0082

XMPP Date and Time Profiles

XEP-0083

Nested Roster Groups

XEP-0084

User Avatar

XEP-0085

Chat State Notifications

XEP-0086

Error Condition Mappings

XEP-0091

Legacy Delayed Delivery

XEP-0092

Software Version

XEP-0096

File Transfer

XEP-0100

Gateway Interaction

XEP-0106

JID Escaping

XEP-0107

User Mood

Server support via Personal Eventing Protocol (XEP-0163)

XEP-0108

User Activity

Server support via Personal Eventing Protocol (XEP-0163)

XEP-0114

Jabber Component Protocol

XEP-0115

Entity Capabilities

XEP-0118

User Tune

Server support via Personal Eventing Protocol (XEP-0163)

XEP-0124

Bidirectional-streams Over Synchronous HTTP (BOSH)

XEP-0128

Service Discovery Extensions

XEP-0127

Common Alerting Protocol (CAP) Over XMPP

XEP-0131

Stanza Headers and Internet Metadata (SHIM)

XEP-0133

Service Administration

XEP-0136

Message Archiving

XEP-0141

Data Forms Layout

XEP-0142

Workgroup Queues

XEP-0144

Roster Item Exchange

XEP-0145

Annotations

XEP-0146

Remote Controlling Clients

XEP-0152

Reachability Addresses

XEP-0153

vCard-Based Avatars

XEP-0155

Stanza Session Negotiation

XEP-0156

Discovering Alternative XMPP Connection Methods

Uses DNS records, so will work with Tigase XMPP Server

XEP-0157

Contact Addresses for XMPP Services

XEP-0160

Best Practices for Handling Offline Messages

XEP-0163

Personal Eventing Protocol

XEP-0166

Jingle

XEP-0167

Jingle RTP Sessions

XEP-0170

Recommended Order of Stream Feature Negotiation

XEP-0171

Language Translation

XEP-0172

User Nickname

XEP-0174

Serverless Messaging

XEP-0175

Best Practices for Use of SASL ANONYMOUS

XEP-0176

Jingle ICE-UDP Transport Method

XEP-0177

Jingle Raw UDP Transport Method

XEP-0178

Best Practices for Use of SASL EXTERNAL with Certificates

XEP-0179

Jingle IAX Transport Method

XEP-0180

Jingle Video via RTP

XEP-0181

Jingle DTMF

XEP-0184

Message Receipts

XEP-0185

Dialback Key Generation and Validation

XEP-0190

Best Practice for Closing Idle Streams

XEP-0191

Blocking Command

XEP-0198

Stream Management

Both Session Resumption and Stanza Acknowledgements

XEP-0199

XMPP Ping

XEP-0201

Best Practices for Message Threads

XEP-0202

Entity Time

XEP-0203

Delayed Delivery

XEP-0205

Best Practices to Discourage Denial of Service Attacks

XEP-0206

XMPP Over BOSH

XEP-0209

Metacontacts

XEP-0220

Server Dialback

XEP-0223

Persistent Storage of Private Data via PubSub

XEP-0224

Attention

XEP-0225

Component Connections

XEP-0226

Message Stanza Profiles

XEP-0231

Bits of Binary

XEP-0234

Jingle File Transfer

XEP-0245

The /me Command

XEP-0246

End-to-End XML Streams

XEP-0247

Jingle XML Streams

XEP-0249

Direct MUC Invitations

XEP-0250

C2C Authentication Using TLS

XEP-0251

Jingle Session Transfer

XEP-0260

Jingle SOCKS5 Bytestreams Transport Method

XEP-0261

Jingle In-Band Bytestreams Transport

XEP-0262

Use of ZRTP in Jingle RTP Sessions

XEP-0277

Microblogging over XMPP

XEP-0280

Message Carbons

XEP-0292

vCard4 Over XMPP

XEP-0301

In-Band Real Time Text

XEP-0305

XMPP Quickstart

XEP-0313

Message Archive Management

XEP-0323

Internet of Things - Sensor Data

XEP-0324

Internet of Things - Provisioning

XEP-0325

Internet of Things - Control

XEP-0326

Internet of Things - Concentrators

XEP-0333

Chat Markers

XEP-0352

Client State Indication

✓footnote:commercial[]

XEP-0357

Push Notifications

XEP-0363

HTTP File Upload

XEP-0368

SRV records for XMPP over TLS

Requires adding DNS entries pointing to port 5223

XEP-0387

XMPP Compliance Suites 2018

3.7. Tigase Custom Extensions

3.7.1. General features

Table 6. Monitoring

Support

Name

Comment

✓footnote:commercial[Requires commercial license]

AuditLog

Ability functionality to log important events in a system (loggins, message exchanges, calls)

✓footnote:commercial[]

Anti Abuse

Fight stanza SPAM, DoS, brute-force attacks and other threats

Virtual domains

Ability to create and manage multiple virtual domains from a single instance and restart-less management

MUC subscribe for offline push

Option to register permanently to the room to receive push notifications about new messages.

Scripting API

Supports the Java Scripting API JSR-223

JMX monitoring

Advanced monitoring the server via JMX protocol with an API for connecting custom monitors and TCP/IP end-point for connecting general purpose JMX tools

HTTP monitoring

Basic monitoring via HTTP protocol

XMPP Monitoring

Pluggable, active monitoring via XMPP, retrieving detailed server statistics, receiving automatic notifications about possible problems discovered by the self-monitor mechanisms

SNMP Monitoring

Advanced server monitoring via SNMP.

Bosh Cache

Bosh Session Cache - a feature to quickly reload user data - roster, presences and messages history by the web client (for example after web page reload)

Clustering

Full clustering support for HA and LB with pluggabble clustering strategies for perfect optimising the cluster to the client’s system

✓footnote:commercial[]

Advanced Clustering Strategy

Dedicated, specialised clustering strategy for best possible performance

✓footnote:commercial[]

MUC Clustered

Support for clustering group chatrooms with various, pluggable strategies

✓footnote:commercial[]

PubSub Clustered

Support for clustering PubSub component with various, pluggable strategies

Mobile optimisations

Optimizations designed for Mobile Devices

OSGi

Support for running in OSGi environment, i.e. as embedded XMPP server in advanced application server

Dynamic rosters

Ability to create users' rosters entries on the fly based on data retrieved from any sources

Command line admin tools

Commandline utility to manage server

✓footnote:commercial[]

Unified Archive

An extension to XEP-0313 Message Archive Management, with greatly improved flexibility in terms of what can be archived.

3.7.2. Repositories/Databases

Table 7. Repositories/Databases

Support

Name

Comment

DB per domain

Ability to have multiple databases for specific domains.

PostgreSQL

Full support for PostgreSQL database with database schemas excluding dedicated DB schema for PubSub component

MySQL

Full support for MySQL database with database schemas, dedicated DB schema for PubSub component

SQL Server

Full support for MS SQL Server database with database schemas excluding dedicated DB schema for PubSub component, only in Tigase server version 3.x

Derby DB

Full support for built-in Derby database with database schemas excluding dedicated DB schema for PubSub component

JDBC

Support for all JDBC enabled databases, although the database schemas are available for some databases

Drupal Auth

Drupal authentication - the Tigase server can share user authentication database with Drupal CMS and authenticate users agains Drupal user database

Drupal Auth

Close integration with Drupal CMS, the Tigase can send notifications to subscribed users about new posts, comments and can also publish short news information via XMPP

LDAP-Auth

LDAP Authentication Connector Supported

4. Licensing and Open Source

As mentioned previously, Tigase is open source under AGPLv3. If you are not familiar with open source software, or the environment, here are some frequently asked questions that might provide some answers.

What does open source mean?
This means that Tigase’s source code is available to the public to see how Tigase works. There are no 'black boxes' for packets where things just happen, everything is out in the open, whereas other companies may consider this propitiatory information. In addition, we have the benefit of many talented people working with Tigase to constantly improve Tigase server and related projects. These people not only include the Tigase development team, but other members of the community who submit code improvements, patches, enhancements, or other changes to Tigase.

Does this mean that the binaries are open to malicious code?
Although we accept patches from contributors, our repository does not accept them directly. Code may be submitted through our tigase.tech page and our developers will review the code before it is added. All builds are tested for functionality and security when they are built.

Does this mean it is less secure?
Not at all. Although anybody can see the source code, and know how Tigase works; your installation, connections, and settings are uniquely yours. Tigase is regularly tested and written to be as secure as possible using the latest encryption and secure connection protocols.

Is Tigase free?
Tigase is free for download and use in it’s unmodified state. Our commercial grade products such as Advanced Clustering Strategy is available for free use for testing & development.

Does this mean I cannot use it in my product or commercial environment?
Not necessarily, consult the Affero General Public License Agreement v3 to see if your use qualifies. Tigase is offered under commercial license if your use is not covered by AGPLv3.

Are there options for closed code or extensions?
Yes! Commercial licenses can be custom made for each client, and software written for your company may be made private or part of our open source distributions at your discretion.

Can I contribute code?
Sure! We accept code through GitHub pull-requests - submit them to one of our projects listed in our GitHub organisation

5. Tigase Server Binary Updates

Most open source projects try to make sure that the nightly builds compile correctly so that these builds can be used. However, we at Tigase believe that these builds should be separated until they are thoroughly tested and released. Although lots of installations out there we know of just run from our nightly builds, this puts an extra responsibility to make sure all code is functional and will constantly work. Therefore, our general approach is to run all basic functionality tests before each code commit to make sure it works correctly. This does not guarantee that there will never be a problem, but it is a precaution from preventing bad builds from arriving in the hands of our customers.

Some users on the other hand, like to be on the bleeding edge and regularly use our nightly builds exploring new code changes and playing with new features before they are put to a full release. Others prefer to stick to stable and fully tested public releases. Others however, want something from the middle, the most recent features, but bug fixes, something like a beta or a release-candidate state.

Should you choose to use the nightly builds, a few things you should consider:

  • Changes may be made to the code that can negatively affect performance.

  • Changes may be made to the code that can negatively affect security.

We highly recommend testing these builds in your environments before upgrading.

With these considerations in mind, we provide nightly builds at this link which provides directories by date.

Standard naming format is tigase-server-<version>-SNAPSHOT-b<build>-<type> where <version> is in the form of major.minor.bugfix

Note
individual days may have the same builds as noted by the byyyy section of the file.*

Just like the standard distributions, the builds are available with the following extensions (<type>):

  1. javadoc.jar - Java installer for javadoc only

  2. dist.zip - Compressed binaries with no dependencies.

  3. dist.tar.gz - tarball compressed binaries with no dependencies.

  4. dist-max.zip - Compressed binaries with all dependencies.

  5. dist-max.tar.gz - tarball compressed binaries with all dependencies.

We also provide automated testing of each of our nightly builds for each supported databases. Tests are done with both functional and low memory parameters in mind, and are available at this link. These tests can provide a quick examination of function before upgrading your current build.

6. Quick Start Guide

6.1. Minimum Requirements

Before you begin installing Tigase server onto your system, please make sure the minimum requirements are met first:

  • Java Development Kit (JDK) 11 (LTS) - We recommend OpenJDK

  • Administrator access - We recommend that you install Tigase Server from a user login with administrator access.

Important
You should always run the latest point/bugfix release of the recommended JDK.
Note
While it should be possible to use newer versions of the JDK, we don’t guarantee it and we recommend using the one mentioned above.

6.2. Contents

This is a set of documents allowing you to quickly start with our software. Every document provides an introduction to a single topic allowing you to start using/developing or just working on the subject. Please have a look at the documents list below to find a topic you are looking for. If you don’t find a document for the topic you need please let us know.

6.3. Installation Using Web Installer

When Tigase XMPP Server starts up, it looks for the default configuration file: etc/config.tdsl. If this file has not been modified you can run the web installer. Which will step you through the process of configuring Tigase. If you are installing Tigase in a Windows environment, please see the Windows Installation section.

6.3.1. Download and Extract

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

$ tar -xf tigase-server-<version>-dist-max.tar.gz
$ cd tigase-server-<version>
Tip
Do not run as root user!

6.3.2. Start the Server

Note
Please make sure JAVA_HOME is set and points to your JVM installation
scripts/tigase.sh start etc/tigase.conf

6.3.3. Verify Tigase is ready to start installation

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

$ lsof -i -P
COMMAND   PID   USER   FD   TYPE   DEVICE SIZE/OFF NODE NAME
java    18387 tigase  141u  IPv6 22185825      0t0  TCP *:8080 (LISTEN)

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

6.3.4. Connect to the Web Installer

Some points before you can connect:

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

This combination will only be valid once as it will be removed from config.tdsl file on completion of setup process. After this point the setup page will only be accessible using the following:

  1. JID accounts listed as administrators in admins line in config.tdsl file.

  2. Username and password combinations added to config.tdsl file manually, or at the last page in this process.

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

Enter the username and password above to gain access.

6.3.5. Step Through the Installation Process

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

web install 01

Read it and then click "Next"

web install 02

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

web install 03

This page will look over your basic configuration settings, these include the server type, domains you wish to use, and gives you a chance to specify an administrator for the domain. Also, you will be selecting what type of database Tigase server will be using (configuration comes later). If you do not specify an administrator and password, one is made for you, which will be admin@yourdomain and password is tigase. If you wish to configure your server beyond the basics, check Advanced configuration options.

web install 04

The Advanced configuration page. Select what components and configurations you need. Some may be highlighted red to indicate conflicts or unmet requirements.

web install 05

Plugins which will be loaded by the server, most plugins are enabled by default. Some may be highlighted red to indicate conflicts or unmet requirements.

web install 06

This is where the database is setup. The type of database selected in step 3 will influence available options. BE SURE TO SPECIFY DATABASE ROOT USER ACCOUNT AND PASSWORD

web install 07

You should see a page like this after a successful database setup. This page will reveal any issues with your database setup such as invalid URIs, passwords, and schemas. You may hit Back on your browser to check credentials and settings and try again.

web install 08

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

web install 09

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

web install 10

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

web install 11

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

6.3.6. Restart the Server

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

./scripts/tigase.sh stop

./scripts/tigase.sh start etc/tigase.conf
Note
In order to make Tigase XMPP Server start automatically during system startup you should setup startup scripts as described in Tigase Script Selection

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

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

6.3.7. Verify Tigase is Running

You should see a list of listening ports.

$ lsof -i -P
COMMAND   PID   USER   FD   TYPE   DEVICE SIZE/OFF NODE NAME
java    18387 tigase  141u  IPv6 22185825      0t0  TCP *:8080 (LISTEN)
java    18387 tigase  148u  IPv6 22185834      0t0  TCP *:5222 (LISTEN)
java    18387 tigase  149u  IPv6 22185835      0t0  TCP *:5223 (LISTEN)
java    18387 tigase  150u  IPv6 22185836      0t0  TCP *:5290 (LISTEN)
java    18387 tigase  151u  IPv6 22185837      0t0  TCP *:5280 (LISTEN)
java    18387 tigase  152u  IPv6 22185838      0t0  TCP *:5269 (LISTEN)

6.3.8. Windows Instructions for using Web Installer

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

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

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

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

6.4. Manual Installation in Console Mode

Our preferred way to install the Tigase server is using Web installer and configuration program which comes with one of the binary packages. Please pick up the latest version of the distribution archive in our download section.

In many cases however it is not always possible to use the web installer. In many cases you have just an ssh access or even a direct access in console mode only. We are going to provide a text-only installer in one of the next releases but for the time being you can use our binary packages to install the server manually. Please continue reading to learn how to install and setup the server in a few easy steps…​

If you have an old version of the Tigase server running and working and you intend to upgrade it please always backup the old version first.

Note
Please note that these instructions are for *nix operating systems, and some modifications may be required for other Operating Systems!

6.4.1. Get the Binary Package

Have a look at our download area. Always pick the latest version of the package available. For manual installation either zip or tar.gz file is available. Pick one of files with filename looking like: tigase-server-<version>-b<build>-<type>.<archive>, where <version> is in the form of major.minor.bugfix, <type> can be either dist (basic package) or dist-max (extended set of components) and archive type can be eitehr tar.gz or zip.

6.4.2. Unpack the Package

Unpack the file using command for the tar.gz file:

 $ tar -xzvf tigase-server-x.y.z-bv.tar.gz

or for the zip file:

 $ unzip tigase-server-x.y.z-bv.zip

A new directory will be created: tigase-server-x.y.z-bv/.

Sometimes after unpacking package on unix system startup script doesn’t have execution permissions. To fix the problem you have to run following command:

 $ chmod u+x ./scripts/tigase.sh

6.4.3. Prepare Configuration

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

 $ ls -l
total 88
drwxr-xr-x 2 tigase tigase  4096 Aug 15 18:17 certs
-rw-r--r-- 1 tigase tigase     0 Aug 15 18:26 ChangeLog
drwxr-xr-x 2 tigase tigase 12288 Aug 15 18:17 database
drwxrwxr-x 4 tigase tigase  4096 Oct 12 09:48 docs
drwxrwxr-x 2 tigase tigase  4096 Oct 12 09:48 etc
drwxrwxr-x 2 tigase tigase  4096 Oct 12 09:48 jars
-rw-r--r-- 1 tigase tigase 34203 Aug 15 18:26 License.html
drwxr-xr-- 2 tigase tigase  4096 Aug 15 18:26 logs
-rw-r--r-- 1 tigase tigase  3614 Aug 15 18:26 package.html
-rw-r--r-- 1 tigase tigase  2675 Aug 15 18:26 README
drwxr-xr-x 9 tigase tigase  4096 Aug 15 18:17 scripts
drwxr-xr-x 5 tigase tigase  4096 Aug 15 18:17 tigase
drwxrwxr-x 4 tigase tigase  4096 Oct 12 09:48 win-stuff

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

 $ ls -l etc/
total 36
-rw-r--r-- 1 tigase tigase  153 Aug 15 18:11 bosh-extra-headers.txt
-rw-r--r-- 1 tigase tigase  325 Aug 15 18:11 client-access-policy.xml
-rw-r--r-- 1 tigase tigase  124 Aug 15 18:11 config.tdsl
-rw-r--r-- 1 tigase tigase  263 Aug 15 18:11 cross-domain-policy.xml
-rw-r--r-- 1 tigase tigase 2337 Aug 15 18:11 jmx.access
-rw-r--r-- 1 tigase tigase 2893 Aug 15 18:11 jmx.password
-rw-r--r-- 1 tigase tigase  735 Aug 15 18:11 logback.xml
-rw-r--r-- 1 tigase tigase 3386 Aug 15 18:11 snmp.acl
-rw-r--r-- 1 tigase tigase 1346 Aug 15 18:11 tigase.conf
Configure tigase.conf

Tigase.conf is a file that contains general program operating parameters, and java settings for Tigase to run. For now, the only setting we need to set is the JAVA_HOME directory.

JAVA_HOME="${JDKPath}"

Replace ${JDKPath} with a path to Java JDK installation on your system.

Configure config.tdsl

You need also to edit the config.tdsl file. It contains initial parameters normally set by the configuration program. As this is a manual installation, you will have to edit this document yourself. It contains already a few lines:

'config-type' = 'setup'

http () {
    setup () {
        'admin-user' = 'admin'
        'admin-password' = 'tigase'
    }
}

You will need to set a few things in order to get Tigase up and running.

Step 1: Change config-type

Refer to config-type property description for details, but for most operations, change setup to default.

Step 2: Set virtual host

Without a virtual host, your XMPP server has no domain with which to operate. To set a virtual host use the following configuration:

'default-virtual-host' = 'hostname'

You have to replace hostname with a domain name used for your XMPP installation. Let’s say this is jabber.your-great.net. Your setting should look like this:

'default-virtual-host' = 'jabber.your-great.net'

There are many other settings that can be configured visit this section for details.

Step 3: Set Administrators

At least one administrator is required, and once the database is setup will have the default password of tigase. Be sure to change this once you have finished setting up your server. To add admins, use the following line in the config.tdsl file:

admins = [ 'admin@jabber.your-great.net', 'user2jabber.your-great.net' ]
Step 4: Set databases

You will also need to configure connection to the database. First you have to decide what database you want to use: Derby, MySQL, PostgreSQL, MSSQL, or MondoDB. Each database will have slightly different configurations. If we are using derby, in a directory called tigasedb, your configuration would look like this:

dataSource () {
    default () {
        uri = 'jdbc:derby:tigasedb;create=true'
    }
}

Consult dataSource property for more configuration info.

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

6.4.4. Install Database

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

./scripts/tigase.sh install-schema etc/tigase.conf -T derby -D tigasedb -H localhost -U tigase_user -P tigase_pass -R root -A rootpass -J admin@jabber.your-great.net -N pass

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

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

C:\tigase>java -cp "jars/*" tigase.db.util.SchemaManager "install-schema" -T derby -D tigasedb -H localhost -U tigase_user -P tigase_pass -R root -A rootpass -J admin@jabber.your-great.net -N pass

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

LogLevel: CONFIG
2017-10-12 20:05:47.987 [main]             DBSchemaLoader.init()                   CONFIG:   Parameters: [ingoreMissingFiles: false, logLevel: CONFIG, adminPassword: pass, admins: [admin@jabber.your-great.net], dbRootPass: rootpass, dbRootUser: root, dbType: derby, dbName: tigasedbx, dbHostname: localhost, dbUser: tigase_user, dbPass: tigase_pass, useSSL: false, useLegacyDatetimeCode: false, serverTimezone: null, file: null, query: null]
Oct 12, 2017 8:05:48 PM tigase.util.DNSResolverDefault <init>
WARNING: Resolving default host name: ubuntu took: 7
Oct 12, 2017 8:05:49 PM tigase.db.util.SchemaManager loadSchemas
INFO: found 1 data sources to upgrade...
Oct 12, 2017 8:05:49 PM tigase.db.util.SchemaManager loadSchemas
INFO: begining upgrade...
LogLevel: CONFIG
2017-10-12 20:05:49.877 [main]             DBSchemaLoader.init()                   CONFIG:   Parameters: [ingoreMissingFiles: false, logLevel: CONFIG, adminPassword: pass, admins: [admin@jabber.your-great.net], dbRootPass: rootpass, dbRootUser: root, dbType: derby, dbName: tigasedbx, dbHostname: null, dbUser: null, dbPass: null, useSSL: null, useLegacyDatetimeCode: false, serverTimezone: null, file: null, query: null]
2017-10-12 20:05:49.877 [main]             DBSchemaLoader.validateDBConnection()   INFO:     Validating DBConnection, URI: jdbc:derby:tigasedbx;create=true
2017-10-12 20:05:50.932 [main]             DBSchemaLoader.validateDBConnection()   CONFIG:   DriverManager (available drivers): [org.apache.derby.jdbc.AutoloadedDriver@65262308, jTDS 1.3.1, com.mysql.jdbc.Driver@54997f67, com.mysql.fabric.jdbc.FabricMySQLDriver@189633f2, org.postgresql.Driver@76fc5687]
2017-10-12 20:05:50.932 [main]             DBSchemaLoader.validateDBConnection()   INFO:     Connection OK
2017-10-12 20:05:50.933 [main]             DBSchemaLoader.validateDBExists()       INFO:     Validating whether DB Exists, URI: jdbc:derby:tigasedbx;create=true
2017-10-12 20:05:50.936 [main]             DBSchemaLoader.withConnection()         CONFIG:   DriverManager (available drivers): [org.apache.derby.jdbc.AutoloadedDriver@65262308, jTDS 1.3.1, com.mysql.jdbc.Driver@54997f67, com.mysql.fabric.jdbc.FabricMySQLDriver@189633f2, org.postgresql.Driver@76fc5687]
2017-10-12 20:05:50.937 [main]             DBSchemaLoader.lambda$validateDBExists$283()  INFO: Exists OK
2017-10-12 20:05:50.939 [main]             DBSchemaLoader.loadSchemaFile()         INFO:     Loading schema from file(s): database/derby-schema-7-2.sql, URI: jdbc:derby:tigasedbx;create=true
2017-10-12 20:05:50.941 [main]             DBSchemaLoader.withConnection()         CONFIG:   DriverManager (available drivers): [org.apache.derby.jdbc.AutoloadedDriver@65262308, jTDS 1.3.1, com.mysql.jdbc.Driver@54997f67, com.mysql.fabric.jdbc.FabricMySQLDriver@189633f2, org.postgresql.Driver@76fc5687]
2017-10-12 20:05:51.923 [main]             DBSchemaLoader.lambda$loadSchemaFile$287()  INFO:  completed OK
2017-10-12 20:05:51.925 [main]             DBSchemaLoader.loadSchemaFile()         INFO:     Loading schema from file(s): database/derby-message-archiving-schema-1.3.0.sql, URI: jdbc:derby:tigasedbx;create=true
2017-10-12 20:05:51.926 [main]             DBSchemaLoader.withConnection()         CONFIG:   DriverManager (available drivers): [org.apache.derby.jdbc.AutoloadedDriver@65262308, jTDS 1.3.1, com.mysql.jdbc.Driver@54997f67, com.mysql.fabric.jdbc.FabricMySQLDriver@189633f2, org.postgresql.Driver@76fc5687]
2017-10-12 20:05:52.209 [main]             DBSchemaLoader.lambda$loadSchemaFile$287()  INFO:  completed OK
2017-10-12 20:05:52.210 [main]             DBSchemaLoader.loadSchemaFile()         INFO:     Loading schema from file(s): database/derby-muc-schema-2.5.0.sql, URI: jdbc:derby:tigasedbx;create=true
2017-10-12 20:05:52.211 [main]             DBSchemaLoader.withConnection()         CONFIG:   DriverManager (available drivers): [org.apache.derby.jdbc.AutoloadedDriver@65262308, jTDS 1.3.1, com.mysql.jdbc.Driver@54997f67, com.mysql.fabric.jdbc.FabricMySQLDriver@189633f2, org.postgresql.Driver@76fc5687]
2017-10-12 20:05:52.305 [main]             DBSchemaLoader.lambda$loadSchemaFile$287()  INFO:  completed OK
2017-10-12 20:05:52.306 [main]             DBSchemaLoader.loadSchemaFile()         INFO:     Loading schema from file(s): database/derby-pubsub-schema-3.3.0.sql, URI: jdbc:derby:tigasedbx;create=true
2017-10-12 20:05:52.307 [main]             DBSchemaLoader.withConnection()         CONFIG:   DriverManager (available drivers): [org.apache.derby.jdbc.AutoloadedDriver@65262308, jTDS 1.3.1, com.mysql.jdbc.Driver@54997f67, com.mysql.fabric.jdbc.FabricMySQLDriver@189633f2, org.postgresql.Driver@76fc5687]
2017-10-12 20:05:52.731 [main]             DBSchemaLoader.lambda$loadSchemaFile$287()  INFO:  completed OK
2017-10-12 20:05:52.732 [main]             DBSchemaLoader.addXmppAdminAccount()    INFO:     Adding XMPP Admin Account, URI: jdbc:derby:tigasedbx;create=true
2017-10-12 20:05:52.732 [main]             DBSchemaLoader.addXmppAdminAccount()    CONFIG:   RepositoryFactory.getAuthRepository(null, jdbc:derby:tigasedbx;create=true,{data-repo-pool-size=1})
Oct 12, 2017 8:05:52 PM tigase.db.jdbc.DataRepositoryImpl initialize
INFO: Table schema found: jdbc:derby:tigasedbx;create=true, database type: derby, database driver: org.apache.derby.jdbc.EmbeddedDriver
Oct 12, 2017 8:05:52 PM tigase.db.jdbc.DataRepositoryImpl initialize
INFO: Initialized database connection: jdbc:derby:tigasedbx;create=true
2017-10-12 20:05:52.884 [main]             DBSchemaLoader.addXmppAdminAccount()    INFO:     All users added
2017-10-12 20:05:52.884 [main]             DBSchemaLoader.postInstallation()       INFO:     Post Installation, URI: jdbc:derby:tigasedbx;create=true
2017-10-12 20:05:52.891 [main]             DBSchemaLoader.withConnection()         CONFIG:   DriverManager (available drivers): [org.apache.derby.jdbc.AutoloadedDriver@65262308, jTDS 1.3.1, com.mysql.jdbc.Driver@54997f67, com.mysql.fabric.jdbc.FabricMySQLDriver@189633f2, org.postgresql.Driver@76fc5687]
2017-10-12 20:05:52.892 [main]             DBSchemaLoader.lambda$postInstallation$286()  INFO: Finalizing...
2017-10-12 20:05:52.893 [main]             DBSchemaLoader.lambda$postInstallation$286()  INFO:  completed OK
2017-10-12 20:05:52.895 [main]             DBSchemaLoader.shutdownDerby()          INFO:     Validating DBConnection, URI: jdbc:derby:tigasedbx;create=true
2017-10-12 20:05:53.129 [main]             DBSchemaLoader.withConnection()         SEVERE:


=====
Failure: Database 'tigasedbx' shutdown.
=====


Oct 12, 2017 8:05:53 PM tigase.db.util.SchemaManager loadSchemas
INFO: schema upgrade finished!




  =============================================================================
  	Schema installation finished

  Data source: default with uri jdbc:derby:tigasedbx;create=true
  	Checking connection to database	ok
  	Checking if database exists	ok
  	Loading schema: Tigase XMPP Server (Core), version: 8.0.0	ok
  	Loading schema: Tigase Message Archiving Component, version: 1.3.0	ok
  	Loading schema: Tigase MUC Component, version: 2.5.0	ok
  	Loading schema: Tigase PubSub Component, version: 3.3.0	ok
  	Adding XMPP admin accounts	ok
  	Post installation action	ok

  Example etc/config.tdsl configuration file:

  'config-type' = 'default'
  debug = [ 'server' ]
  'default-virtual-host' = [ 'ubuntu' ]
  dataSource () {
      default () {
          uri = 'jdbc:derby:tigasedbx;create=true'
      }
  }
  amp () {}
  bosh () {}
  c2s () {}
  eventbus () {}
  http () {}
  'message-archive' () {}
  monitor () {}
  muc () {}
  pubsub () {}
  s2s () {}
  ws2s () {}
  =============================================================================

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

6.4.5. Start the Server

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

./scripts/{OS}/init.d/tigase start etc/tigase.conf

Where {OS} is your *nix operating system.

and you should get the output like this:

Starting Tigase:
nohup: redirecting stderr to stdout
Tigase running pid=18103

6.4.6. Check if it is Working

The server is started already but how do you know if it is really working and there were no problems. Have a look in the logs/ directory. There should be a few files in there:

 $ ls -l logs/
total 40K
-rw-r--r-- 1 20K 2009-02-03 21:48 tigase-console.log
-rw-r--r-- 1 16K 2009-02-03 21:48 tigase.log.0
-rw-r--r-- 1   0 2009-02-03 21:48 tigase.log.0.lck
-rw-r--r-- 1   6 2009-02-03 21:48 tigase.pid

The first 2 files are the most interesting for us: tigase-console.log and tigase.log.0. The first one contains very limited information and only the most important entries. Have a look inside and check if there are any WARNING or SEVERE entries. If not everything should be fine.

Now you can connect with an XMPP client of your choice with the administrator account you setup earlier.

6.5. Windows Installation

Tigase XMPP Server can also work on Microsoft Windows systems and servers, although some slight modifications may be necessary to get things ready to run.

Although you may wish to use command line, take note that commands entered in shell may require quotations in some cases.

Make sure that you have Java JDK v8 installed on your system prior to installing Tigase. It will also help to fully setup whatever database software you will be using as well.

6.5.1. Step 1: Initial Setup

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

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

copy "tigase.ico" "..\"
copy "wrapper\wrapper.jar" "..\jars"
copy "wrapper\wrapper.dll" "..\jars"
copy "wrapper\wrapper.exe" "..\"
copy "wrapper\wrapper.conf" "..\"
copy "wrapper\wrapper-community-license-1.2.txt" "..\"
copy "scripts\*.*" "..\"

6.5.2. Step 2: Starting Server

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

java -cp "jars/*" tigase.server.XMPPServer
Note
this may freeze the command window, and will only display output from Tigase.

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

2A: Installing as a service

The cleanest way to operate Tigase in a Windows environment is to install Tigase as a Service by running the InstallTigaseService.bat program. This will install Tigase as a system service, and now the server can be controlled from the services.msc panel. This allows for stopping, starting, and pausing of Tigase XMPP Server and allowing for graceful shutdowns.

For a basic installation, MySQL is recommended over Derby DB. For that purpose, we have included a basic installation guide for MySQL on Windows systems here:

6.5.3. MySQL Database Installation

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

Download the binary package from MySQL download area at mysql.com. Make sure you select executable proper for your operating system.

Run the installation program and follow default installation steps. When the installation is complete find the MySQL elements in the Windows Start menu and run the MySQL Configuration Wizard. Follow the wizard and make sure to check settings against the screenshots in the guide below.

In Welcome window just press 'Next'.(pic.1)

sql1

In the next window select option: 'Detailed Configuration' and press 'Next' (pic. 2)

sql2

On the next screen select option: 'Server Machine' and press 'Next' (pic. 3)

sql3

On the forth windows leave the default" 'Multi-functional Database' and press 'Next' (pic. 4)

sql4

On the step number five just press 'Next' using defaults. (pic. 5)

sql5

Again, on window 6 select the default - 'Decision Support (DSS)/OLAP' and press 'Next' (pic.6)

sql6

Make sure you switch OFF the 'Strict mode' and and press 'Next' (pic. 7)

sql7

On the character encoding page select: 'Manual Selected Default Character set/ Collation' and 'utf8', press 'Next' (pic.8)

sql8

On next window select 'Include Bin Directory in Windows PATH' and press 'Next' (pic.9)

sql9

On this window just enter the database super user password and make sure you remember it. When ready press 'Next' (pic. 10)

sql10

This is the last screen. Press 'Execute' to save the configuration parameters. (pic. 11)

sql11

When the configuration is saved you can repeat all the steps and change settings at any time by running: START ⇒ Programs ⇒ MYSQL⇒ MYSQL serwer machine⇒ MySQL Server Instance Config Wizard

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

  1. Create the database:

    mysql>create database tigasedb;
  2. Add database user:

    mysql> GRANT ALL ON tigasedb.* TO tigase_user@'%' IDENTIFIED BY 'tigase_passwd';
    mysql> GRANT ALL ON tigasedb.* TO tigase_user@'localhost' IDENTIFIED BY 'tigase_passwd';
    mysql> GRANT ALL ON tigasedb.* TO tigase_user IDENTIFIED BY 'tigase_passwd';
    mysql> FLUSH PRIVILEGES;
  3. Load Tigase database schema:

    mysql> use tigasedb;
    mysql> source c:/Program Files/Tigase/database/mysql-schema.sql;

When the system is up and running you can connect with any XMPP client (Psi for example) to your server to see if it is working.

6.6. Tigase Server Network Instructions

One you have installed Tigase XMPP Server on a machine, you’re going to want to use it. If you are just using for local communications on a network behind a router, you’re all set. Enjoy and use!

However, if you want to have people from other computers outside your network connect to your server, you’re going to have to go through a few more steps to show your server out to the public.

Note
This guide is merely a recommendation of how to get a local server to be open to incoming communications. Any time you open ports, or take other security measures you risk compromising your network security. These are only recommendations, and may not be appropriate for all installations. Please consult your IT Security expert for securing your own installation.

XMPP, being a decentralized communication method, relies on proper DNS records to figure out where and how an XMPP server is setup. Operating an XMPP Server will require you to properly setup DNS routing so not only can clients connect to you, but if you decide to run a federated server and enable server to server communication, you will need to do the same. If you already have a DNS server already, you should have little issue adding these records. If you do not have a DNS setup pointing to your server, you may use a free dynamic name service such as dynu.com.

6.6.1. A Records

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

6.6.2. SRV Records

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

SRV records have the following form:

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

The key is as follows:

  • service: is the symbolic name of the desired service, in this case it would be xmpp-client or xmpp-server.

  • protocol: is the transport protocol, either TCP or UDP, XMPP traffic will take place over TCP.

  • name: the domain name where the server resides, in this case tigase.org.

  • TTL: a numeric value for DNS time to live in milliseconds, by default use 86400.

  • class: DNS class field, this is always IN.

  • priority: the priority of the target host with lower numbers being higher priority. Since we are not setting up multiple SRV records, we can use 0.

  • weight: the relative weight for records with the same priority. We can use 5.

  • port: the specific TCP or UDP port where the service can be found. In this case it will be 5222 or 5269.

  • target: the hostname of the machine providing the service, here we will use xmpp.tigase.org.

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

_xmpp-client._TCP.tigase.org 86400 IN SRV 0 5 5222 xmpp.tigase.org
_xmpp-server._TCP.tigase.org 86400 IN SRV 0 5 5269 xmpp.tigase.org
Tigase and Vhosts

If you are running multiple vhosts or subdomains that you wish to separate, you will need another record. In this case an A record will be all you need if you are using default ports. If you are using custom ports, you will need to have a new SRV record for each subdomain.

6.6.3. Hosting via Tigase.me

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

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

$ host -t SRV _xmpp-server._tcp.your-domain.tld
_xmpp-server._tcp.your-domain.tld has SRV record 10 0 5269 tigase.me.
$ host -t SRV _xmpp-client._tcp.your-domain.tld
_xmpp-client._tcp.your-domain.tld has SRV record 10 0 5222 tigase.me.
$ host -t SRV _xmpps-client._tcp.your-domain.tld
_xmpp-client._tcp.your-domain.tld has SRV record 10 0 5222 tigase.me.

If you want to have MUC and PubSub available under your domain as subdomains, you have to setup DNS for your muc.your-domain.tld and pubsub.your-domain.tld domains too.

For MUC:

$ host -t SRV _xmpp-server._tcp.muc.your-domain.tld
_xmpp-server._tcp.muc.your-domain.tld has SRV record 10 0 5269 tigase.me.

For PubSub :

$ host -t SRV _xmpp-server._tcp.pubsub.your-domain.tld
_xmpp-server._tcp.pubsub.your-domain.tld has SRV record 10 0 5269 tigase.me.

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

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

Providing certificate

It’s also encouraged to provide dedicated SSL certificate - there are various ways to do it and they are described in Installing/Loading Certificate To the Tigase Server. You may want to take advantage of free Let’s Encrypt certificates and automate whole upload and renewal process as described in Installing LetsEncrypt Certificates in Your Linux System

6.6.4. Checking setup

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

6.6.5. Ports description

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

  • 3478 - TURN or STUN, plain socket, TCP and UDP

  • 5349 - TURN or STUN, over TLS, TCP and UDP

  • 5222 - incoming client to server XMPP connections

  • 5223 - incoming client to server XMPP connections over TLS/SSL, including DirectTLS

  • 5269 - default s2s port, i.e.: federation support

  • 5277 - inter-cluster communication

  • 5280 - default BOSH connections

  • 5290 - default WebSocket connections

  • 5291 - default WebSocket connections over TLS/SSL

  • 8080 - for HTTP server (web-based setup, REST API, file upload extension, etc.)

  • 9050 - JMX Monitoring

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

iptables -A INPUT -p tcp -m tcp --dport 5222 -j ACCEPT
iptables -A INPUT -p tcp -m tcp --dport 5223 -j ACCEPT
iptables -A INPUT -p tcp -m tcp --dport 5269 -j ACCEPT
iptables -A INPUT -p tcp -m tcp --dport 5277 -j ACCEPT
iptables -A INPUT -p tcp -m tcp --dport 5280 -j ACCEPT
iptables -A INPUT -p tcp -m tcp --dport 5290 -j ACCEPT
iptables -A INPUT -p tcp -m tcp --dport 8080 -j ACCEPT
iptables -A INPUT -p tcp -m tcp --dport 9050 -j ACCEPT

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

  1. change ports in Tigase configuration and update DNS SRV records;

  2. forward those ports to default Tigase ports (this is especially useful under *nix operating system if you want to utilize ports lower than 1024 while running, as recommended, Tigase service from user account - there is a limitation and user accounts can bind to ports lower than 1024), for example using iptables rules (in following example we are making available Tigase SSL websocket port available under port 443, which is usually opened in corporate firewalls):

    iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-ports 5291

6.7. Tigase Script Selection

As mentioned in each of the quick start sections, each distribution of Tigase XMPP server comes with a number of scripts that are customized for different versions of Linux.

Table 8. init.d chart
Operating system init.d file path Types of Operating Systems

Systemd

tigase-server/scripts/systemd/*

Systemd-based distributions

Debian

tigase-server/scripts/debian/tigase.init.d

Knoppix, Ubuntu (before v15.04), Raspbian or Duvian

Gentoo

tigase-server/scripts/gentoo/init.d/tigase

CoreOS (before v94.0.0), Tin Hat Linux or other *too based systems

Mandriva

tigase-server/scripts/mandriva/init.d/tigase

Specific init.d file for Mandriva Linux

Redhat

tigase-server/scripts/redhat/init.d/tigase

RedHat (before v7.0) and other RPM based linux derivatives like CentOS (before v.7.14), openSUSE (before v12.2)

Note
If your operating system is a systemd-based linux distribution, we recommend to use systemd service scripts. It may be possible to use (in this case legacy) init.d startup files as before, but usage of systemd startup scripts will allow better control of the startup process and will even allow for automatic restart of the Tigase XMPP Server in the case of JVM crash.

6.7.1. Configuration: For Linux Distributions using systemd

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

sudo cp $SCRIPT_FILE_PATH/tigase-server.service /etc/systemd/system/

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

  • User - Specifies the user that will run the program. This should be a user with SU permissions.

  • WorkingDirectory - Specifies installation directory (default: /home/tigase/tigase-server)

  • ExecStart - Specifies startup command (default: runs scripts/tigase.sh start etc/tigase.conf in the Tigase installation directory)

  • ExecStop - Specifies shutdown command (default: runs scripts/tigase.sh stop etc/tigase.conf in the Tigase installation directory)

  • PIDFile - Specifies location of the PID file (default: logs/tigase.pid file in the Tigase installation directory)

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

sudo cp $SCRIPT_FILE_PATH/tigase-server /etc/default/

With those files in place you need to reload systemctl daemon

sudo systemctl daemon-reload
Note
If you are upgrading from the previous version of the Tigase XMPP Server which was not running as the systemd system service it is required to uninstall old service and remove old service files.

6.7.2. Configuration: For All Linux Distributions

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

sudo cp $SCRIPT_FILE_PATH /etc/init.d/tigase

You may also need to make it executable:

sudo chmod +x /etc/init.d/tigase

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

Gentoo

The conf.d script must contain the following parameters:

TIGASE_HOME="/home/tigase/tigase-server"
TIGASE_USER=tigase
TIGASE_CONF="etc/tigase.conf"

The following should be configured:

  • TIGASE_HOME - Specifies the Tigase Server installation directory.

  • TIGASE_USER - Specifies the user that will run the program. This should be a user with SU permissions.

  • TIGASE_CONF - The location of tigase.conf file, relative to the TIGASE_HOME directory.

Mandriva

Mandriva has a single init.d file, however it should be configured:

…
export JAVA_HOME=/usr/java/jdk1.8.0
export TIGASE_DIR=/opt/tigase/server/
tigase=$TIGASE_DIR/scripts/tigase.sh
prog=tigase
config=$TIGASE_DIR/etc/tigase.conf
…

The following should be configured:

  • JAVA_HOME - The location of your JDK Installation.

  • TIGASE_DIR - Tigase Server installation directory.

  • tigase - The location of your tigase.sh script. This should not need adjusting if you maintain the default file structure.

  • config - The location of your tigase.conf file. This should not need adjusting if you maintain the default file structure.

pid file will be stored in /var/run/ser.pid

Redhat

Similar to Mandriva, you will need to configure the init.d file:

…
JAVA_HOME=/usr/lib/jvm/java/

USERNAME=tigase
USERGROUP=tigase
NAME=tigase
DESC="Tigase XMPP server"

TIGASE_HOME=/home/tigase/tigase-server
TIGASE_LIB=${TIGASE_HOME}/jars
TIGASE_CONFIG=/etc/tigase.conf
TIGASE_OPTIONS=
TIGASE_PARAMS=

PIDFILE=
TIGASE_CONSOLE_LOG=
…
  • USERNAME - Username running Tigase, should have su permissions.

  • USERGROUP - The usergroup of the username.

  • NAME - OS name for Tigase program.

  • DESC - Optional description.

  • TIGASE_HOME - The location of your Tigase Server installation directory.

  • TIGASE_LIB - The location of your Tigase Jars folder, you should not need to adjust this if you set TIGASE_HOME properly, and maintain the default file structure.

  • TIGASE_CONFIG - The location of your tigase.conf file relative to TIGASE_HOME

  • TIGASE_OPTIONS - Legacy options for Tigase, most are now handled in config.tdsl or tigase.conf.

  • TIGASE_PARAMS - Parameters passed to command line when launching Tigase.

  • PIDFILE - Location of Tigase PID file if you wish to use custom directory. Default will be located in /logs or /var/temp directory.

  • TIGASE_CONSOLE_LOG - Location of Tigase Server console log file if you wish to use a custom directory. Default will be located in /logs directory, failing that /dev/null.

After you’ve copied the script, in order to install sysinit script you have to add it to the configuration:

/sbin/chkconfig --add tigase

Service can be enabled or disabled service with:

/sbin/chkconfig tigase <on|off|reset>
Debian

As with other distributions you should copy init.d script to the correct location. Afterwards it should be edited and correct values for variables need to be set:

…
USERNAME=tigase
USERGROUP=tigase
NAME=tigase
DESC="Tigase XMPP server"

TIGASE_HOME=/usr/share/tigase
TIGASE_CONFIG=/etc/tigase/tigase.config
TIGASE_OPTIONS=
TIGASE_PARAMS=

PIDFILE=
TIGASE_CONSOLE_LOG=
…
  • USERNAME - Username running Tigase, should have su permissions.

  • USERGROUP - The usergroup of the username.

  • NAME - OS name for Tigase program.

  • DESC - Optional description.

  • TIGASE_HOME - The location of your Tigase Server installation directory.

  • TIGASE_CONFIG - The location of your tigase-server.xml file relative (old configuration format)

  • TIGASE_OPTIONS - command line arguments passed to Tigase server (which may include path to init.properies (if correct tigase.conf configuration will be found then it will translate to TIGASE_OPTIONS=" --property-file etc/config.tdsl "

  • TIGASE_PARAMS - Parameters passed to command line when launching Tigase.

  • PIDFILE - Location of Tigase PID file if you wish to use custom directory. Default will be located in /var/run/tigase/tigase.pid or under (in this case relative to tigase home directory)logs/tigase.pid.

  • TIGASE_CONSOLE_LOG - Location of Tigase Server console log file if you wish to use a custom directory. Default will be located in /logs directory, failing that /dev/null.

Afterwards we need to install service in the system with following command:

update-rc.d tigase defaults

6.7.3. Running Tigase as a system service

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

For systemd-based linux distributions

Once installation is complete you may start Tigase as a typical systemd service using following command:

sudo systemctl start tigase-server

To stop it, you may run following command:

sudo systemctl stop tigase-server

It is also possible to enable service, to make it start during startup of the operating system:

sudo systemctl enable tigase-server
For other linux distributions

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

service tigase start

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

  • service tigase stop

  • service tigase restart

6.8. Shutting Down Tigase

Although Tigase XMPP Server can be terminated by ending the process, it is preferred and recommended to use it’s own shutdown scripts instead. Not only does this allow for a proper purge of Tigase form the system, but allows for all shutdown functions to operate, such as amending logs and completing statistics. To trigger a shutdown of Tigase server, the following command can be used from the tigase directory:

./scripts/tigase.sh stop

You may specify the config file if you want, but it will make no differences

This will:

  • Begin shutdown thread

  • Stop accepting new connections

  • Close all current connections

  • Collect runtime statistics

  • Write statistics to log

  • Dump full stacktrace to a file

  • Run GC and clear from memory

6.8.1. Shutdown statistics

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

6.8.2. Shutdown StackTrace Dump

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

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

'shutdown-thread-dump' = false

6.8.3. Shutting Down Cluster Nodes

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

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

6.9. Upgrading to v8.0.0 from v7.1.0

There have been a number of changes to the user and auth databases since v7.1.0. As a result, if you are upgrading from older versions, you will need to follow this guide.

Note
We recommend installing Tigase XMPP Server 8.0.0 in a separate directory.

6.9.1. Backup your data

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

For MySQL databases:

mysqldump [dbname] --routines -u [username] -p [password] > [filename].sql

6.9.2. Setup Tigase XMPP Server 8.0.0

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

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

cd tigase-server-8.0.0
cp ../tigase-server/etc/tigase.conf etc/
cp ../tigase-server/etc/init.properties etc/

Import the database.

mysql -h [host address] [dbname] -u [username] -p [password] < [filename].sql
mysql -h 198.27.120.213 tigase_tpub -u USERNAME -p <../tpub.2017-05-30.sql
Enter password:

6.9.3. Upgrade configuration file

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

./scripts/tigase.sh upgrade-config etc/tigase.conf

When everything is ready it will printout following information

=============================================================================
  Configuration file etc/init.properties was converted to DSL format.
  Previous version of a configuration file was saved at etc/init.properties.old
=============================================================================

6.9.4. Connect new database

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

dataSource {
    default () {
        uri = 'jdbc:mysql://localhost/tigase_tpub?user=tigase_user&password=mypass'
    }
}
userRepository {
    default () {}
}
authRepository {
    default () {}
}

6.9.5. Upgrade Database schema

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

./scripts/tigase.sh upgrade-schema etc/tigase.conf
Warning
Your database schema MUST be v8 or conversion will not occur properly!

You will be asked the following prompts:

Database root account username used to create tigase user and database at 198.27.120.213 :

Database root account password used to create tigase user and database at 198.27.120.213 :

Upon success, you should see the following:

=============================================================================
        Schema upgrade finished

  Data source: default with uri
jdbc:mysql://HOST/DATABASE?user=USERNAME&password=PASSWORD
        Checking connection to database ok
        Checking if database exists     ok
        Loading schema: Tigase XMPP Server (Core), version: 8.0.0       ok
        Loading schema: Tigase Message Archiving Component, version: 1.3.0      ok
        Loading schema: Tigase MUC Component, version: 2.5.0    ok
        Loading schema: Tigase PubSub Component, version: 3.3.0 ok
        Adding XMPP admin accounts      warning
                Message: Error: No admin users entered
        Post installation action        ok

=============================================================================

Start Tigase!

6.9.6. Help?

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

scripts/tigase.sh upgrade-config etc/tigase.conf --help
scripts/tigase.sh upgrade-schema etc/tigase.conf --help

6.9.7. Upgrade/Restore with a script [experimental!]

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

It’s usage is as follows:

./tigase-upgrade.sh {upgrade|rollback} install_package install_directory [tar|dir]

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

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

$ ./tigase-upgrade.sh upgrade tigase-server-8.0.0-SNAPSHOT-b5285-dist-max.tar.gz tigase-server

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

bash -x ./tigase-upgrade.sh rollback tigase-server-8.0.0-SNAPSHOT-b5264_backup-18-11-05_1712/ tigase-server

7. Configuration

When the user tries to setup the client for the first time he comes across 2 configuration files: tigase.conf and config.tdsl in the /etc folder. Here is a brief explanation what all those files are about and in other sections you can learn all the details needed to configure the server.

  1. config.tdsl file is a simple text file with server parameters in form: key = value. When the XML configuration file is missing the Tigase server reads config.tdsl file and uses parameters found there as defaults for generation of the XML file. Therefore if you change the config.tdsl file you normally have to stop the server, remove the XML file and start the server again. All the settings from the config.tdsl are read and applied to the XML configuration. The properties file is easy to read and very safe to modify. At the moment this is the recommended way change the server configuration.

  2. tigase.conf is the Tigase server startup configuration. It is actually not used by the server itself. It rather contains operating system settings and environment parameters to correctly run the Java Virtual Machine. It is only useful on the unix-like systems with Bash shell. If you run the server on MS Windows systems tigase.bat and wrapper.conf files are used instead. The tigase.conf file is read and loaded by the scripts/tigase.sh shell script which also scans the operating system environment for Java VM and other tools needed.

7.1. DSL file format

In previous Tigase XMPP Server releases configuration was stored in properties based configuration file. From Tigase XMPP Server 8.0.0 release it will be required to use new DSL based configuration file format. This file format was inspired by Groovy language syntax and new core feature of Tigase XMPP Server - Tigase Kernel Framework.

7.1.1. Why new format?

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

c2s/ports[i]=5222,5223

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

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

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

--comp-name-1=pubsub
--comp-class-1=tigase.pubsub.PubSubComponent
pubsub/test[B]=true
pubsub/pubsub-repo-url="jdbc:XXXX:XXXX/db_name"

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

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

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

7.1.2. What is DSL?

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

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

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

--comp-name-1=pubsub
--comp-class-1=tigase.pubsub.PubSubComponent
pubsub/test[B]=true

In DSL based configuration this would be replaced by following block

pubsub (class: tigase.pubsub.PubSubComponent) {
    # comment
    test = true
}

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

Warning
If a string value assigned to a property contains any char from a following list =:,[]#+-*/ it needs to be wrapped in a ''.

7.1.3. Why DSL?

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

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

./scripts/tigase.sh upgrade-config etc/tigase.conf
Setting property

To set property you just write property name followed by = and value to set. This is always done in context of bean which configuration property you want to set.

test=true

It is also possible to set property in main context by placing property outside of any context. This sets property which value is available to access by any bean.

Setting global property

Like in properties file it is still possible to use property names starting with -- without any context or any other properties at global scope. Format is the same as in case of setting property but they are defined without scope (in global scope). This properties are global and accessible by any bean but also set as system property in JVM.

Defining bean

You can configure bean by using following format:

beanName (class: className, active: activeValue, exportable: exportableValue) {
    # scope of bean properties
}

where beanName is name under which you want to configure bean. beanName must be wrapped in '', if beanName contains characters like =:,[]#+-*/ and is recommended, if beanName is numeric only.

Inside block between ( and ) you can define:

  • class which will be used as a bean, in example above we set class as className. (default: if you try to configure bean under name which has default class assigned with it in Tigase framework then this assigned class will be used. In other case you need to pass name of class to use as a bean)

  • active (boolean) whether you want the bean to be active or not (beans with active set to false are not loaded). (default: true)

  • exportable (boolean) defines if this bean should be exported and available for use for beans in inner scopes. This is advanced option in most cases it is recommended to omit this field in configuration. (default: false)

Spaces between beanName and block between () is optional as well as space between block () and block {}. It is recommended that properties of bean would be placed in separate lines with indentation and first property will be placed in new line.

Important

Usage of () block is very important. When this block is used in configuration it automatically sets active property of bean definition for bean for which it is used to to true. This is done due to fact that default value of active is true.

If you omit it in configuration, you will set bean configuration but it may remain inactive. In this state bean will not be loaded and as a result will not be used by Tigase XMPP Server.

Configuring bean

If you know that bean is defined and you do not want to change it’s activity or class then you can just pass properties to configure bean in following way:

beanName {
    # scope of bean properties
    test = true
}

where beanName is name of bean to configure and test is name of property to set to true in this bean.

Format of values

In properties based configuration file every property was defined as a string and only by defining expected format it was properly converted to expected value. In DSL it is possible to set values in two ways:

as an object

Using this format you set list as a list and integer is set as an integer.

Type Description

string

Wrap it in '', ie. to set test as string you use 'test'

integer

Just put value, ie. to set 543 use 543

long

Put value and follow it with L, ie. to set 23645434 as long use 23645434L

float

Put value and follow it with f, ie. to set 231.342 use 231.342f

boolean

To set value just use true or false

list

Lists can be of many types and to make it simple we decided to use as a comma separated list of values in proper format wrapped in [].

  • of strings - [ 'alfa', 'beta', 'gamma' ]

  • of integers - [ 1, 2, 3, 4]

You can write it in multiple lines if you want:

[
    'alfa'
    'beta'
    'gamma'
]

map

Maps can be written as a block of properties wrapped in {}. This format of map is the same as used for passing configuration to bean properties. Keys and values can be written in separate lines (recommended):

{
    test = true
    ssl = false
    ssl-certificate = '/test/cert.pem'
    another-map = {
        key = 'value'
    }
}

or in single line (separation with spaces is not required):

{ test = true, ssl = false, ssl-certificate = '/test/cert.pem' }
as a plain string

Very similar to properties based configuration, in fact values are passed in same format and later are converted to correct type by checking type expected by bean. (Not recommended)

Type Description

string

Just put value, ie. to set test use test

integer

Just put value, ie. to set 543 use 543

long

Put value, ie. to set 23645434 as long use 23645434

float

Put value, ie. to set 231.342 use 231.342

boolean

To set value just use true or false

list

List needs to be written as comma separated list of values, ie. test,abc,efg or 1,2,3

map

Not possible

Using values from System Properties and Environment Variables

Now it is possible to use values of system properties and environment variables and assign them to bean properties. For this purpose we added functions which can be used in DSL and which will return values of:

system property

prop('property-name') or prop('property-name','default value')

environment variable

env('variable-name')

Example of setting value of system property and environment variable to bean user
user {
  name = env('USER')
  home = prop('user.home')
  paths = [ prop('user.home'), prop('user.dir') ]
}
Warning
For properties which accepts lists it is not allowed to set value using variable/property with comma separated values like value1,value2 wrapped in [], ie. property = [ env('some-variable') ]. It needs to be set in following way property = env('some-variable')
Computed values

With DSL configuration format we introduce support for computable values for properties. It is now possible to set value which is result of a computation, ie. concatenation of a strings or very simple mathematical expression. We currently support only following mathematical operations:

  • add

  • subtract

  • multiply

  • divide

Example of setting environment variable related path and computed timeout
bean {
  # setting path to `some-subdirectory` of user home directory
  path = prop('user.home') + '/some-subdirectory/'

  # setting timeout to 5 minutes (setting value in milliseconds)
  timeout = 5L * 60 * 1000
  # previously it would need to be configured in following way:
  # timeout = 300000L
}
Warning
For properties which accepts lists it is not allowed to set value using computed values with comma separated values like value1,value2 wrapped in [], ie. property = [ env('some-variable') + ',other-value' ]. It needs to be set in following way property = env('some-variable') + ',other-value'.
Period / Duration values

Some configuration options allow control of execution of tasks with particular period or within certain duration. DSL file format accepts strings denoting particular amount of time, which follows Java’s native structures (see: Period and Duration for detailed explanation).

  • Duration formats accepted are based on the ISO-8601 duration format PnDTnHnMn.nS with days considered to be exactly 24 hours, for example:

    • PT20.345S - 20.345 seconds

    • PT15M - 15 minutes (where a minute is 60 seconds)

    • PT10H - 10 hours (where an hour is 3600 seconds)

    • P2D - 2 days (where a day is 24 hours or 86400 seconds)

    • P2DT3H4M - 2 days, 3 hours and 4 minutes

  • Period format is based on the ISO-8601 period formats PnYnMnD and PnW, for example, the following are valid inputs:

    • P2Y - 2 years

    • P3M - 3 months

    • P4W - 4 weeks

    • P5D - 5 days

    • P1Y2M3D - 1 year, 2 months, 3 days

    • P1Y2M3W4D - 1 year, 2 months, 3 weeks, 4 days

7.1.4. Example configuration file in DSL

# Enable cluster mode
--cluster-mode = true
# Enable debugging for server and xmpp.impl
--debug = 'server,xmpp.impl'
# Set list of virtual hosts (old way)
--virt-hosts = 'example.com,test-1.example.com,test-2.example.com'

# Configure list of administrator jids
admins = [ 'admin@zeus', 'http@macbook-pro-andrzej.local' ]
# Set config type
config-type = '--gen-config-def'

# Configure dataSource bean with database configuration
dataSource {
    # Configure default data source (using default implementation so class is omitted)
    default () {
        uri = 'jdbc:postgresql://127.0.0.1/tigase?user=test&password=test&autoCreateUser=true'
    }

    # Configure data source with name exaple.com (will be used by domain example.com)
    'example.com' () {
        uri = 'jdbc:mysq://127.0.0.1/example?user=test&password=test&autoCreateUser=true'
    }
}

# Configure C2S component
c2s {
    # Enable Stream Management bean
    'urn:xmpp:sm:3' () {}

    # Register tigase.server.xmppclient.SeeOtherHostDualIP as seeOtherHost bean
    seeOtherHost (class: tigase.server.xmppclient.SeeOtherHostDualIP) {}

    # Add additional port 5224 which is SSL port and disable port 5223
    connections () {
        '5224' () {
	         socket = ssl
	      }
        '5223' (active: false) {}
    }
}

# Configure HTTP API component
http {
    # Set list of API keys
    api-keys = [ 'test1234', 'test2356' ]
    rest {
        # Set value of environment property as a path to look for REST scripts
        rest-scripts-dir = env('TIGASE_REST_SCRIPTS_DIR')
    }
}

# Register pubsub-2 (class is passed as pubsub-2 name do not have default class assigned)
pubsub-2 (class: tigase.pubsub.cluster.PubSubComponentClustered) {
    # Set configuration bean properties
    pubsubConfig {
        persistentPep = true
    }
    # Use tigase.pubsub.cluster.ClusteredNodeStrategy as advanced clustering strategy
    strategy (class: tigase.pubsub.cluster.ClusteredNodeStrategy) {}
}

# Configure Session Manager
sess-man {
    # Here we enable pep, urn:xmpp:mam:1 processors and disable message-archive-xep-0136 processor
    pep () {}
    'urn:xmpp:mam:1' () {}
    message-archive-xep-0136 (active: false) {}

    # Define class used as clustering strategy (it is different than default so class is required)
    strategy (class: tigase.server.cluster.strategy.OnlineUsersCachingStrategy) {}
}

7.1.5. Default configuration

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

'config-type' = 'setup'

http () {
    setup () {
        'admin-user' = 'admin'
    'admin-password' = 'tigase'
    }
}

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

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

7.2. Startup File for tigase.sh - tigase.conf

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

Config file for startup script simply sets number of environment variables with the 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.

  • JAVA_OPTIONS - options for JVM like size of RAM allocated for the JVM, properties and so on.

  • TIGASE_OPTIONS - (optional) additional options for Tigase server program. You can tweak initial parameters for your environment here. If you want to specify custom location of your configuration file you should use --config-file <path/to/config.tdsl> configuration

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

Please note encoding settings. JVM by default uses encoding set in operating system environment. XMPP protocol, however uses UTF-8 for all data processing. So the ENC settings enforces UTF-8 encoding for all operations.

Another significant setting is \'CLASSPATH'. It is intentionally set to an empty string. The tigase.sh startup script builds the CLASSPATH on it’s own from files found in jars/ and libs/ directories. It is advised 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 can cause a long startup time and high system loads.

7.3. Linux Settings for High Load Systems

There are a few basic settings you have to adjust for high load systems to make sure the server has enough resources to handle a big number of network connections.

The main parameter is a maximum number of opened files allowed for the process to keep at the same time. Each network connection uses a file handler, therefore if the limit is too low you can quickly run out of handlers and the server can not accept any more connections.

This limit is set on 2 levels - on the kernel level (fs.file-max) and on the system level (nofile).

Another kernel property which can be important in certain configurations (like transports installations or when you use proxy for Bosh connections) is: net.ipv4.ip_local_port_range. This parameter can be set the same way as the fs.file-max property.

7.3.1. fs.file-max

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

# sysctl fs.file-max
fs.file-max = 358920

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

# sysctl -w fs.file-max=360000
fs.file-max = 360000

7.3.2. net.ipv4.ip_local_port_range

You can see current settings by executing the command:

# sysctl net.ipv4.ip_local_port_range
net.ipv4.ip_local_port_range = 32768	61000

You can change this setting by executing the command:

# sysctl -w net.ipv4.ip_local_port_range="1024 65000"
net.ipv4.ip_local_port_range = 1024 65000

7.3.3. TCP_keepalive

According to www.gnugk.org/ some keepalive settings should be changed to improve reliability - it will enable keep alive functionality (checking if the connection is established and valid) and, by decreasing times and interval - will make detection of broken connections faster.

# sysctl -w net.ipv4.tcp_keepalive_time="60"
net.ipv4.tcp_keepalive_time = 60
# sysctl -w net.ipv4.tcp_keepalive_probes="3"
net.ipv4.tcp_keepalive_probes = 3
# sysctl -w net.ipv4.tcp_keepalive_intvl="90"
net.ipv4.tcp_keepalive_intvl = 90

7.3.4. /etc/sysctl.conf

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

fs.file-max=360000
net.ipv4.ip_local_port_range=1024 65000
net.ipv4.tcp_keepalive_time=60
net.ipv4.tcp_keepalive_probes=3
net.ipv4.tcp_keepalive_intvl=90

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

Command:

# sysctl -p

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

7.3.5. nofile

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

# ulimit -a
core file size          (blocks, -c) 0
data seg size           (kbytes, -d) unlimited
file size               (blocks, -f) unlimited
pending signals                 (-i) 38912
max locked memory       (kbytes, -l) 32
max memory size         (kbytes, -m) unlimited
open files                      (-n) 40960
pipe size            (512 bytes, -p) 8
POSIX message queues     (bytes, -q) 819200
stack size              (kbytes, -s) 8192
cpu time               (seconds, -t) unlimited
max user processes              (-u) 38912
virtual memory          (kbytes, -v) unlimited
file locks                      (-x) unlimited

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

# ulimit -a -H
core file size          (blocks, -c) unlimited
data seg size           (kbytes, -d) unlimited
file size               (blocks, -f) unlimited
pending signals                 (-i) 38912
max locked memory       (kbytes, -l) 32
max memory size         (kbytes, -m) unlimited
open files                      (-n) 40960
pipe size            (512 bytes, -p) 8
POSIX message queues     (bytes, -q) 819200
stack size              (kbytes, -s) unlimited
cpu time               (seconds, -t) unlimited
max user processes              (-u) 38912
virtual memory          (kbytes, -v) unlimited
file locks                      (-x) unlimited

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

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

jabber               soft    nofile         350000
jabber               hard    nofile         350000

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

*               soft    nofile         350000
*               hard    nofile         350000

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

7.3.6. su and init script

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

session    required   pam_limits.so

Afterwards the init scripts will respect configured limits.

7.4. JVM settings and recommendations

Tigase configuration file tigase.conf (described in more detail in Startup File for tigase.sh - tigase.conf) mentioned a couple of environmental variables which are related to the operation of the JVM. In this guide we would like to expound on those configuration options and provide hints for the optimal settings.

Settings included in the etc/tigase.conf are as follows:

#GC="-XX:+UseBiasedLocking -XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:NewRatio=2 -XX:+CMSIncrementalMode -XX:-ReduceInitialCardMarks -XX:CMSInitiatingOccupancyFraction=70 -XX:+UseCMSInitiatingOccupancyOnly"
#EX="-XX:+OptimizeStringConcat -XX:+DoEscapeAnalysis -XX:+UseNUMA"

#GC_DEBUG=" -XX:+PrintTenuringDistribution -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintGCTimeStamps -Xloggc:logs/jvm.log -verbose:gc "

#PRODUCTION_HEAP_SETTINGS=" -Xms5G -Xmx5G " # heap memory settings must be adjusted on per deployment-base!
JAVA_OPTIONS="${GC} ${GC_DEBUG} ${EX} ${ENC} ${DRV} ${JMX_REMOTE_IP} -server ${PRODUCTION_HEAP_SETTINGS} ${DNS_RESOLVER} ${INTERNAL_IP} ${EXTERNAL_IP}  -XX:MaxDirectMemorySize=128m "

And while this file utilizes bash variables, JVM configuration options can be used in the same manner on all operating systems.

The guide will consists of two main parts - memory settings and Garbage Collector tweaks descriptions and hints.

We recommend using -server JVM parameter in all cases.

7.4.1. Heap Sizing

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

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

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

Memory consideration - total usage

The HEAP size is not the only thing that affects JVM memory usage. When trying to size accordingly for your usage and machine specification you have to consider other factors that count towards total: loaded classes, threads' stack, JIT code cache, garbage collector and others. In principle consider following equation:

Maximum memory usage = [-Xmx] + [-XX:MaxMetaspaceSize] + number_of_threads * [-Xss] + [-XX:MaxDirectMemorySize]
                       (heap)   (classes)                (threads' stack)             (direct memory)
Note
before Java8 memory dedicated to loaded classes was configured with -XX:PermSize and -XX:MaxPermSize instead of, respectively, -XX:MetaspaceSize and -XX:MaxMetaspaceSize

In case of Tigase XMPP Server, apart from heap we limit remaining factors:

  • direct memory to 128 MB

  • loaded classes to 128 MB

  • single thread’s stack size to 228 KB (number of threads depends on number of CPU cores and may vary from 500 to couple of thousands)

In principle, in addition to HEAP’s maximum size defined by -Xmx you should add roughly 512 MB

If you are interested in detailed tracking of memory take a look at [Memory footprint of the JVM](https://spring.io/blog/2019/03/11/memory-footprint-of-the-jvm/), [Native Memory Tracking in JVM](https://www.baeldung.com/native-memory-tracking-in-jvm) or [Why does my Java process consume more memory than Xmx?](https://plumbr.io/blog/memory-leaks/why-does-my-java-process-consume-more-memory-than-xmx)

7.4.2. GC settings

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

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

Generations
  • Young Generation, which is further divided in to:

    • Eden - the region when the objects are usually allocated when they are created;

    • Survivor Spaces - (to and from - one of which is always empty) - responsible for storing all live object remaining after collecting Young Generation (process is repeated several times until objects are finally considered old enough);

  • Old Generation - (Tenured Space) - responsible for live objects remaining after running GC on Survivor Spaces - those would be long-lived objects (usually user connections and associated data);

Minor, Major and Full GC - optimizing

General thinking suggests that:

  • Minor GC cleans Young generation;

  • Major GC cleans Tenured space;

  • Full GC cleans all heap.

However, while we can certainly state that Minor GC cleans Young generation it’s a bit more difficult to differentiate Major and Full GC, especially considering that Major GC can be quite often triggered by Minor GC and some garbage collectors can perform cleaning concurrently. Instead of focusing of distinguishing phases one should pay closer attention to actual operations of Garbage Collector itself - uncommenting the line GC_DEBUG=" -XX:+PrintTenuringDistribution -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintGCTimeStamps -Xloggc:logs/jvm.log -verbose:gc " in etc/tigase.conf (or adding same properties to the java commandline) and subsequently analyzing the results should prove more helpful. In addition monitoring GC operation using for example VisualVM (with VisualGC plugin) will also be helpful.

Settings for XMPP

Ideally we should limit both number of GC pauses as well as their duration. After running rather tests following conclusions were made:

  • Garbage Collection is the faster the more dead objects occupies given space, therefore on high-traffic installation it’s better to have rather large YoungGen resulting in lower promotion of the objects to the OldGen;

  • with JVM8 default sizing of Young / Old generation changed, even tho NewRatio is still defaulting to “2” - setting it explicitly to "2" brought back previous sizing;

  • Concurrent Mark and Sweep (CMS) enabled (applies to Tenured space only) with explicit configuration of NewRatio set to default value of 2 (i.e. -XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:NewRatio=2) in general behaves best;

  • For small installations (few core CPU, less memory) with low traffic default Parallel collector may be a better solution;

  • Using Heap size adjusted to the actual usage is better as the larger the heap the larger are spaces over which collection needs to be performed thus resulting in longer pauses; in case of huge heaps G1 collector may be better solution to avoid longer pauses;

Considering all of the above using following options should be a good starting point toward further optimizing of Garbage Collection:

GC="-XX:+UseBiasedLocking -XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:+CMSIncrementalMode -XX:-ReduceInitialCardMarks -XX:CMSInitiatingOccupancyFraction=70 -XX:+UseCMSInitiatingOccupancyOnly"

GC settings worth considering

In addition to the general recommendation to use CMS collector, following options (or changes to the options) may be worth considering:

  • -XX:NewRatio=2 - defines the ratio between the young and tenured generation is 1:2. In other words, the combined size of the eden and survivor spaces will be one-third of the total heap size. The parameters NewSize and MaxNewSize bound the young generation size from below and above. Setting these to the same value fixes the young generation, just as setting -Xms and -Xmx to the same value fixes the total heap size.

  • -XX:CMSInitiatingOccupancyFraction=percent - sets the percentage of the old generation occupancy (0 to 100) at which to start a CMS collection cycle.

  • -XX:+UseCMSInitiatingOccupancyOnly - instructs the JVM not to base its decision when to start a CMS cycle on run time statistics but instead it uses the value of CMSInitiatingOccupancyFraction for every CMS cycle.

  • -XX:ParallelGCThreads=x - sets the number of threads used for parallel garbage collection in the young and old generations. The default value depends on the number of CPUs available to the JVM. If the Tigase JMV is the only one running on the installation default value is recommended.

  • -XX:ConcGCThreads=x - sets the number of threads used for concurrent GC. The default value depends on the number of CPUs available to the JVM. If the Tigase JMV is the only one running on the installation default value is recommended.

  • -XX:+UseBiasedLocking and -XX:+DoEscapeAnalysis - designed to eliminate locking overhead, however their effect on performance is unpredictable therefore testing is required; reduced locking should improve concurrency and, on current multi-core hardware, improve throughput.

  • -XX:+OptimizeStringConcat - enables the optimization of String concatenation operations. This option is enabled by default.

  • -XX:+UseNUMA - enables performance optimization of an application on a machine with nonuniform memory architecture (NUMA - most modern computers are based on NUMA architecture) by increasing the application’s use of lower latency memory. By default, this option is disabled and no optimization for NUMA is made. The option is only available when the parallel garbage collector is used (-XX:+UseParallelGC).

  • -XX:-UseCompressedOops — disables the use of compressed pointers. By default, this option is enabled, and compressed pointers are used when Java heap sizes are less than 32 GB. When this option is enabled, object references are represented as 32-bit offsets instead of 64-bit pointers, which typically increases performance when running the application with Java heap sizes less than 32 GB. This option works only for 64-bit JVMs.

7.4.3. What to use with Machine x, y, z?

Server class machine (non-VM), > 16GB, >= 8 core CPU

For such setup enabling CMS garbage collector is recommended. Depending on the traffic usage and particular use-case adjusting NewRatio may be needed. Adjusting Xms and Xms sizes for actual available memory is needed (or better yet, for the actual traffic!). Following should be used:

GC="-XX:+UseBiasedLocking -XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:NewRatio=2 -XX:+CMSIncrementalMode -XX:-ReduceInitialCardMarks -XX:CMSInitiatingOccupancyFraction=70 -XX:+UseCMSInitiatingOccupancyOnly"
EX="-XX:+OptimizeStringConcat -XX:+DoEscapeAnalysis -XX:+UseNUMA"

#GC_DEBUG=" -XX:+PrintTenuringDistribution -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintGCTimeStamps -Xloggc:logs/jvm.log -verbose:gc "

PRODUCTION_HEAP_SETTINGS=" -Xms15G -Xmx15G " # heap memory settings must be adjusted on per deployment-base!
JAVA_OPTIONS="${GC} ${GC_DEBUG} ${EX} ${ENC} ${DRV} ${JMX_REMOTE_IP} -server ${PRODUCTION_HEAP_SETTINGS} ${DNS_RESOLVER} ${INTERNAL_IP} ${EXTERNAL_IP}  -XX:MaxDirectMemorySize=128m "

For installation with lot of available memory and intention to utilize it all, using G1GC collector may be a better idea :

GC="-XX:+UseG1GC -XX:ConcGCThreads=4 -XX:G1HeapRegionSize=2 -XX:InitiatingHeapOccupancyPercent=35 -XX:MaxGCPauseMillis=100"
EX="-XX:+OptimizeStringConcat -XX:+DoEscapeAnalysis -XX:+UseNUMA"

#GC_DEBUG=" -XX:+PrintTenuringDistribution -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintGCTimeStamps -Xloggc:logs/jvm.log -verbose:gc "

PRODUCTION_HEAP_SETTINGS=" -Xms60G -Xmx60G " # heap memory settings must be adjusted on per deployment-base!
JAVA_OPTIONS="${GC} ${GC_DEBUG} ${EX} ${ENC} ${DRV} ${JMX_REMOTE_IP} -server ${PRODUCTION_HEAP_SETTINGS} ${DNS_RESOLVER} ${INTERNAL_IP} ${EXTERNAL_IP}  -XX:MaxDirectMemorySize=128m "
VM machine, 8GB of RAM, 4 core CPU equivalent

For such setup enabling CMS garbage collector is also recommended. Depending on the traffic usage and particular use-case adjusting NewRatio may be needed (and configuring NewRatio is a must!). Adjusting Xms and Xms sizes for actual available memory is needed (or better yet, for the actual traffic!). Following should be used:

GC="-XX:+UseBiasedLocking -XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:NewRatio=2 -XX:+CMSIncrementalMode -XX:-ReduceInitialCardMarks -XX:CMSInitiatingOccupancyFraction=70 -XX:+UseCMSInitiatingOccupancyOnly"
EX="-XX:+OptimizeStringConcat -XX:+DoEscapeAnalysis -XX:+UseNUMA"

#GC_DEBUG=" -XX:+PrintTenuringDistribution -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintGCTimeStamps -Xloggc:logs/jvm.log -verbose:gc "

PRODUCTION_HEAP_SETTINGS=" -Xms7G -Xmx7G " # heap memory settings must be adjusted on per deployment-base!
JAVA_OPTIONS="${GC} ${GC_DEBUG} ${EX} ${ENC} ${DRV} ${JMX_REMOTE_IP} -server ${PRODUCTION_HEAP_SETTINGS} ${DNS_RESOLVER} ${INTERNAL_IP} ${EXTERNAL_IP}  -XX:MaxDirectMemorySize=128m "
VM machine with 4GB or less of RAM, and less than 4 core CPU equivalent

Small installations with limited resources could operate better with default (for JVM versions up to 8, which is the most current at the moment of the writing). Again - depending on the traffic usage and particular use-case adjusting NewRatio may be needed. Adjusting Xms and Xms sizes for actual available memory is recommended (or better yet, for the actual traffic!). Following should be used (i.e. GC line should be commented so the defaults will be used):

#GC="-XX:+UseBiasedLocking -XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:NewRatio=2 -XX:+CMSIncrementalMode -XX:-ReduceInitialCardMarks -XX:CMSInitiatingOccupancyFraction=70 -XX:+UseCMSInitiatingOccupancyOnly"
EX="-XX:+OptimizeStringConcat -XX:+DoEscapeAnalysis -XX:+UseNUMA"

#GC_DEBUG=" -XX:+PrintTenuringDistribution -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintGCTimeStamps -Xloggc:logs/jvm.log -verbose:gc "

PRODUCTION_HEAP_SETTINGS=" -Xms3G -Xmx3G " # heap memory settings must be adjusted on per deployment-base!
JAVA_OPTIONS="${GC} ${GC_DEBUG} ${EX} ${ENC} ${DRV} ${JMX_REMOTE_IP} -server ${PRODUCTION_HEAP_SETTINGS} ${DNS_RESOLVER} ${INTERNAL_IP} ${EXTERNAL_IP}  -XX:MaxDirectMemorySize=128m "

7.5. Session Manager

Tigase Session Manager is where most of Tigase basic options can be configured, and where many operations are controlled from. Changes to session manager can effect operations throughout an entire XMPP installation, so care must be made when changing settings here.

7.5.1. Mobile Optimizations

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

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

}
'sess-man' {
    'urn:xmpp:csi:0' {
        logic = 'tigase.xmpp.impl.MobileV1'
    }
}

Logic Options are:

MobileV1

Keeps all presence stanzas in queue until client is active.

logic = 'tigase.xmpp.impl.MobileV1'
MobileV2

This setting delays delivery of presences while client is in inactive state, but only keeps the last presence for each full jid. This is the default setting for CSI logic.

logic = 'tigase.xmpp.impl.MobileV2'
MobileV3

Keeps the same presence logic as MobileV2, but also queues Message Carbons. Currently not supported by CSI processor, will cause issues.

logic = 'tigase.xmpp.impl.MobileV3'
Disabling CSI

If you wish to not use the ClientStateIndication processor, set the following in your config.tdsl file:

'sess-man' () {
    'urn:xmpp:csi:0' (active: false) {}
}
A note about Mobile Plugins

Previously, you could enable Mobile optimization logic using by enabling Mobile_V1 (){} bean to Session Manager: sess-man () {} bean.

If you have used these in the past, it is recommended you change your system to use the CSI processor with the appropriate mobile processing logic.

If you require v3 logic, or do not wish to use CSI, be sure to disable it using the above option.

7.5.2. threads-pool

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

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

'sess-man' () {
    'amp' () {
        threadsNo = 30
    }
    'presence-state' () {
        threadsNo = 27
    }
}

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

7.5.3. Thread Pool factor

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

'sess-man' () {
    'sm-threads-factor' = 3
}

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

7.5.4. Strategy

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

Any class implementing tigase.cluster.strategy.ClusteringStrategyIfc interface may be used for this setting.

Example:

'sess-man' () {
    strategy (class: tigase.cluster.strategy.SMCachingAllNodes)
}

This replaces the old --sm-cluster-strategy-class setting from v7.1.

7.6. Virtual Hosts in Tigase Server

Tigase server supports multiple virtual hosts in a single server installation. Virtual hosts can be added or removed, enabled or disabled during runtime without restarting the service or disrupting normal operation.

This document describes how virtual hosts work in Tigase server and how to get the most out of this feature in your installation.

The 'default-virtual-host' property allows to define name of the single vhost domain which will be considered a default vhost domain for this installation. It allows you just to configure the domain name. Any additional configuration needs to be configured using ad-hoc commands.

Virtual hosts should be managed using ad-hoc commands or admin ui, visit Add and Manage Domains for description of vhosts management process or visit Specification for ad-hoc Commands Used to Manage Virtual Domains for more information about ad-hoc commands.

If you have components that may not be able to handle multiple vhosts or cluster mode, we have developed a virtual component solution as well, details in the Virtual Components for the Tigase Cluster section.

You may also want to reference the Vhosts API for additional information: - API Description for Virtual Domains Management in Tigase Server.

Tip
If you have a Tigase XMPP Server running in the cluster mode hidden behind some load balancer, or if internal IP or hostname of cluster nodes differ from the DNS name under which it is available from the internet, we would suggest setting a property installation-dns-address of vhost-man component to the DNS name which allows you to connect to all cluster nodes (ie. to the DNS name of the load balancer). This will allow Tigase XMPP Server to do proper DNS lookups to verify that DNS domain name of the virtual host which you will try to add or update points to your XMPP installation.

7.6.1. Default VHost configuration

It’s possible to specify initial default configuration for all Virtual Host in TDSL configuration file (i.e. etc/config.tdsl) for selected parameters. To do so you should specify each configuration option within defaults bean belonging to vhost-man bean:

'vhost-man' () {
    'defaults' () {
        'domain-filter-policy' = null
        's2s-secret' = null
        trusted = null
        'vhost-disable-dns-check' = false
        'vhost-max-users' = 0L
        'vhost-message-forward-jid' = null
        'vhost-presence-forward-jid' = null
        'vhost-register-enabled' = true
        'vhost-tls-required' = false
    }
}

After initial definition of default configuration or after first startup of Tigase XMPP Server it is possible to configure Virtual Host defaults using ad-hoc commands by modifying values for default using ad-hoc as described in Specification for ad-hoc Commands Used to Manage Virtual Domains.

Alternatively, you may edit default Virtual Host configuration (configuration for domain default) using Admin UI which by default is available at http://localhost:8080/admin/.

7.6.2. 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 the specification described in XEP-0050. Extra information required to complete the command is carried as data forms described in 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 config.tdsl configuration file.

Commands are sent to the '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 an account other than admin, 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 end-user information. The client may ignore the 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 one 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>

7.6.3. Virtual Components for the Cluster Mode

Let’s assume you have a cluster installation and you want to include a component in your installation which doesn’t support the cluster mode yet. If you put it on all nodes as a separate instances they will work out of sync and overall functionality might be useless. If you put on one node only it will work correctly but it will be visible to users connected to this one node only.

Ideally you would like to have a mechanism to install it on one node and put some redirections on other nodes to forward all packets for this component to a node where this component is working. Redirection on it’s own is not enough because the component must be visible in service discovery list and must be visible somehow to users connected to all nodes.

This is where the virtual components are handy. They are visible to users as a local normal component, they seem to be a real local component but in fact they just forward all requests/packets to a cluster node where the real component is working.

Virtual component is a very lightweight ServerComponent implementation in Tigase server. It can pretend to be any kind of component and can redirect all packets to a given address. They can mimic native Tigase components as well as third-party components connected over external component protocol (XEP-0114).

Configuration is very simple and straightforward, in fact it is very similar to configuration of any Tigase component. You set a real component name as a name of the component and a virtual component class name to load. Let’s say we want to deploy MUC component this way. The MUC component is visible as muc.domain.oug in the installation. Thus the name of the component is: muc

muc (class: tigase.cluster.VirtualComponent) {}

This is pretty much all you need to load a virtual component. A few other options are needed to point to correct destination addresses for packets forwarding and to set correct service discovery parameters:

}
muc (class: tigase.cluster.VirtualComponent) {
    'disco-category' = 'conference'
    'disco-features' = 'http://jabber.org/protocol/muc'
    'disco-name' = 'Multi User Chat'
    'disco-node' = ''
    'disco-type' = 'text'
    'redirect-to' = 'muc@cluster-node-with-real-muc.domain.our'
}

That’s it.

7.7. Settings for Custom Logging in Tigase

Logging can be an important tool to monitor your server’s health and performance. Logging may be controlled and customized on a per-component basis.

A logging bean has been implemented to allow more fine configuration of each component.

logging () {
    rootLevel = CONFIG
    'packet-debug-full' = true
    loggers = {
        'tigase.server' = {
            level = ALL
        }
        'tigase.conf' = {
            level = FINEST
        }
    }
    handlers = {
        ' java.util.logging.FileHandler' = {
            level = ALL
            append = true
            count = 5
            formatter = 'tigase.util.LogFormatter'
            limit = 10000000
            pattern = 'logs/tigase.log'
        }
        'java.util.logging.ConsoleHandler' = {
            level = WARNING
            formatter = 'tigase.util.LogFormatter'
        }
    }
}

You only need to specify the settings you wish to customize, otherwise they will be left as default.

  • packet-debug-full - controls whether log entries should be obfuscated (all CData of all elements will be replaced by CData size: <length in bytes of the replaced string>) or not; default: false.

  • rootLevel - Defines the root level of logging for all components not otherwise defined. Default is CONFIG

  • loggers - Defines the level of logging for packages running in tigase server. This is similar to the --debug setting, however you must use tigase.{package} format. Default is NONE.

  • handlers - Defines the level of logging for File output and Console output.

    1. FileHandler - is the file output for log files, with the following options:

      1. level - specifies the level of logs to be written, default is ALL.

      2. append - whether to append to the log or replace it during restart. Default is true.

      3. count - number of individual log files to keep at set limit. Default is 5. (default settings will continue appending logs until 5 files at 10MB are reached, then the oldest file will be overwritten.)

      4. formatter - specifies the package to format logging output. Default is tigase.util.LogFormatter.

      5. limit - Byte limit for each log file. Default is 10000000 or 10MB.

      6. pattern - Directory and filename of the log file with respect to the Tigase installation directory. Default is logs/tigase.log.

    2. ConsoleHandler - Determines the formatting for Tigase output to console.

      1. level - specifies the level of logs to be written, default is WARNING.

      2. formatter - specifies the package to format logging output. Default is tigase.util.LogFormatter.

7.7.1. Disabling colored output

If for some reason you don’t want colored output in the logs you can disable it by setting disable_logger_color to true. For convenience, you can uncomment in etc/tigase.conf following line:

#DISABLE_LOGGER_COLOR=" -Ddisable_logger_color=true "

7.7.2. Alternate loggers in Tigase - Logback

It’s possible to use Logback for logging purposes, which offers certain interesting features (async logging, better control over log rotation, on the fly changing logging configuration)

Requirements: * slf4j-api.jar (provided in -dist-max package) * jul-to-slf4j.jar (provided in -dist-max package) * desired logger libraries (for logback it’s logback-classic.jar and logback-core.jar (provided in -dist-max).

Configuration boils down to adding slf4j bridge handler to the list of build-in Java Logger handlers configuration, which in Tigase translates to adding following line to etc/config.tdsl:

logging () {
    rootHandlers = [ 'java.util.logging.ConsoleHandler', 'java.util.logging.FileHandler', 'org.slf4j.bridge.SLF4JBridgeHandler' ]
}

After that etc/logback.xml configuration file will be used.

As stated in [jul-to-slf4j bridge documentation](http://www.slf4j.org/legacy.html#jul-to-slf4j) it’s essential to include LevelChangePropagator to eliminate translation overhead for disabled log statements:

<configuration debug="true">
  <contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator"/>
  ...
</configuration>

NOTE, that it may be prudent to remove configuration of all old JUL logger by appending following to etc/logback.xml configuration:

<configuration debug="true">
  <contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator"/>
    <resetJUL>true</resetJUL>
</configuration>

7.8. Tigase Advanced Options

This section is designed to include a number of advanced configuration options available within Tigase, but may not have a relevant section yet to house them.

7.8.1. Using CAPTCHA for in-band registration

To reduce false or spam registrations to Tigase XMPP Server, there is now the ability to add CAPTCHA forms as a part of the in-band registration. The CAPTCHA will generate a random math equation and ask the user registering a new account to answer it. This may be enabled as a sub-option of enabling registration in config.tdsl:

'sess-man' {
    'jabber:iq:register' {
        captchaRequired = 'true'
    }
}
Note
Because some clients do not refresh a registration form after an unsuccessful attempt, this option allows 3 retries with the same CAPTCHA.

3 unsuccessful attempts will result in the captcha being invalidated and a client will receive an error message.

7.8.2. Enabling Empty Nicknames

Tigase can now support users with empty nicknames. This can be enabled by adding the following code in config.tdsl.

'sess-man' {
    'jabber:iq:roster' {
        empty_name_enabled = 'true'
    }
}

7.8.3. Enable Silent Ignore on Packets Delivered to Unavailable Resources

You can now have Tigase ignore packets delivered to unavailable resources to avoid having a packet bounce around and create unnecessary traffic. You may set this globally, within standard message handling only, or within the AMP component using the following settings:

Globally:

'sess-man' {
    'silently-ignore-message' = 'true'
}

Message Processing Only:

'sess-man' {
    message {
        'silently-ignore-message' = 'true'
    }
}

AMP Component:

'sess-man' {
    amp () {
        'silently-ignore-message' = 'true'
}

7.8.4. Mechanism to count errors within Tigase

A new processor within statistics has been added to count the number of errors that Tigase returns. This processor, named error-counter, will count all errors returned by Tigase, however by default the number is always zero if it is not enabled. It can be found as an MBean object in JMX under ErrorStatistics and contains values for packets with ERROR and grouped by type. To enable counting of these errors, you must ensure the processor is included in your sess-man configuration:

'sess-man' {
    'error-counter' () {}
}
Including stream errors

Stream ERROR packets are not included in the above counter by default as they are processed separately. To enable this to be added to the counter, the following line must be in your config.tdsl file.

c2s {
    'stream-error-counter' () {
        active = true
    }
}
Stream resumption default & max-timeout

SteamManagementIOProcessor now has a setting that can be used to change the maximum timeout time it will wait for reconnection if a client does not send a time to wait. Two settings are now available:

c2s {
    'urn:xmpp:sm:3' {
        'resumption-timeout' = 90
    }
}

The above setting in config.tdsl file will change the default timeout period to 90 seconds.

c2s {
    'urn:xmpp:sm:3' {
        'max-resumption-timeout' = 900
    }
}

This setting will set the maximum time allowed for stream resumption to 900 seconds. This can be handy if you expect a number of mobile phones to connect to your server and want to avoid duplicate messages being sent back and forth.

Automatic subscription approval

You may setup a server to automatically approve presence subscriptions or roster authorizations for all users. Say you were hosting bots and wanted to automate the process. This can be done with the following settings:

'sess-man' () {
    'jabber:iq:roster' {
        'auto-authorize' = 'true'
    }
    'presence-subscription' () {
        'auto-authorize' = 'true'
    }
}

Both of these settings are false by default, and you may use them together or separately.

Note
presence-subscription is current default plugin. If you are using old presence then you should configure the option with correct plugin name.

The following behavior is followed when they are both activated:

  • Upon sending a subscription request - Both contacts will each others' subscription and be added to each others' roster. Presence information will immediately be exchanged between both parties.

  • Upon sending presence with type either unsubscribe or unsubscribed follows the rules defined in RFC regarding processing of these stanzas (i.e. adjusting subscription type of user/contact), but without forwarding those stanzas to the receiving entity to avoid any notifications to the client. However, a roster push is generated to reflect changes to presence in user roster in a seamless manner.

  • Simply adding an item to the roster (i.e. with <iq/> stanza with correct semantics) will also cause an automatic subscription between the user and the contact in a matter explained above.

Abuse Contacts

Tigase has support for XEP-0128: Service Discovery Extensions for providing additional information to the server and component discovery information. One of the important usages for this feature is XEP-0157: Contact Addresses for XMPP Services which describes usage of this feature for providing contact information to server administrators or abuse response team.

To set abuse contact details you should set disco-extensions in property in etc/config.tdsl file with subproperty abuse-addresses set to your abuse address URI (for email you need to prefix it with mailto: and for XMPP address you need to prefix it with xmpp):

'disco-extensions' = {
    'abuse-addresses' = [ 'mailto:abuse@localhost', 'xmpp:abuse@localhost' ]
}
Push Notifications

Tigase XMPP Server comes with support for XEP-0357: Push Notifications allowing user to receive notifications for messages received while his XMPP client is not connected enabled by default.

Disabling notifications

You can disable this feature with following settings:

'sess-man' {
    'urn:xmpp:push:0' (active: false) {}
}
Removing body and sender from notifications

If you wish Tigase XMPP Server not to forward body of the message or sender details in the push notification you can disable that with following settings:

'sess-man' {
    'urn:xmpp:push:0' () {
        'with-body' = false
        'with-sender' = false
    }
}
Enabling push notifications for messages received when all resources are AWAY/XA/DND

Push notifications may also be sent by Tigase XMPP Server when new message is received and all resources of recipient are in AWAY/XA/DND state. To enable this type of notifications you need to enable additional push delivery extension named away in default push processor:

'sess-man' () {
    'urn:xmpp:push:0' () {
        'away' () {}
    }
}

As this behaviour may not be expected by users and users need a compatible XMPP client to properly handle this notifications (XMPP client needs to retrieve message history from server to get actual message), in addition to enabling this plugin on the server, XMPP clients need to explicitly activate this feature. They can do that by including away attribute with value of true in push enable element send to the server, as in following example:

Enabling Push notifications for away/xa/dnd account
<iq type='set' id='x43'>
  <enable xmlns='urn:xmpp:push:0' away='true' jid='push-5.client.example' node='yxs32uqsflafdk3iuqo'>
    <x xmlns='jabber:x:data' type='submit'>
        ....
    </x>
  </enable>
</iq>

If later on, user decides to disable notification for account in away/xa/dnd state, it may disable push notifications or once again send stanza to enable push notification but without away attribute being set:

<iq type='set' id='x43'>
  <enable xmlns='urn:xmpp:push:0' away='true' jid='push-5.client.example' node='yxs32uqsflafdk3iuqo'>
    <x xmlns='jabber:x:data' type='submit'>
        ....
    </x>
  </enable>
</iq>

8. Security

The articles here cover advanced security features built into to Tigase Server, and some options for adding your own levels of security.

8.1. XEP-0191: Blocking Command

The simplest security feature, however, inside an XMPP server is the ability to block users and JIDS. XEP-0191 specifies the parameters of simple blocking without using privacy lists. Below is a breakdown and some sample commands you may find helpful. To enable this feature, be sure the following is in your config.tdsl file:

}
'sess-man' {
    'urn:xmpp:blocking' () {}
}

If you have other plugins running, then just add 'urn:xmpp:blocking' () {} to the list to activate this feature.

To confirm if your installation of Tigase supports this feature, a quick disco#info of your server should reveal the following feature:

<feature var='urn:xmpp:blocking'/>

Blocked users are stored on the server on a per-JID basis, so one user may only see his or her blocked JIDs. Lists of blocked JIDs will return as an IQ stanza with a list of <item> fields. To retrieve the blocklist, the following command is issued:

<iq type='get' id='blockedjids'>
  <blocklist xmlns='urn:xmpp:blocking'/>
</iq>

The server responds:

<iq type='result' id='blockedjids'>
  <blocklist xmlns='urn:xmpp:blocking'>
    <item jid='user1@domain.net'/>
    <item jid='admin@example.com'/>
  </blocklist>
</iq>

To block a JID, a similar stanza to the one above is sent to the server with the items of the blocked JIDs you wish to add:

<iq from='admin@domain.net' type='set' id='block'>
  <block xmlns='urn:xmpp:blocking'>
    <item jid='user2@domain.net'/>
  </block>
</iq>

The server will then push an unavailable presence to blocked contacts. Communication between a contact that is blocked, and an entity that blocked it will result in a <not-acceptable> error:

<message type='error' from='user2@domain.net' to='admin@domain.net'>
  <body>Hello, are you online?</body>
  <error type='cancel'>
    <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <blocked xmlns='urn:xmpp:blocking:errors'/>
  </error>
</message>

Unblocking a contact is just as easy as blocking, send an unblock stanza to the server:

<iq from='admin@domain.net' type='set' id='unblock'>
  <unblock xmlns='urn:xmpp:blocking'>
    <item jid='user2@domain.net'/>
  </unblock>
</iq>

The server will begin pushing presence information to unblocked contacts and resources so long as permissions have not changed between.

You may also opt to unblock all contacts and essentially clear out your blocked list using the following command:

<iq type='set' id='unblockall'>
  <unblock xmlns='urn:xmpp:blocking'/>
</iq>

8.2. Account Registration Limits

In order to protect Tigase servers from DOS attacks, a limit on number of account registrations per second has been implemented. This may be configured by adding the following line in the config.tdsl file:

'registration-throttling' () {
    limit = 10

This setting allows for 10 registrations from a single IP per second. If the limit is exceeded, a NOT_ALLOWED error will be returned.

It is possible to create two separate counters as well:

'registration-throttling' () {
    limit = 10
}
c2s {
    'registration-throttling' (class: tigase.server.xmppclient.RegistrationThrottling) {
        limit = 3
    }
}

Here we have one for c2s with a limit of 3, and a global for all other connection managers set at 10.

You can also set individual components limits as well:

ws2s {
    'registration-throttling' (class: tigase.server.xmppclient.RegistrationThrottling) {
        limit = 7
    }
}

8.3. Brute-force attack prevention

Brute-force Prevention is designed to protect Tigase Server against user password guessing. It counts invalid login tries and when it is above limit, it locks login ability for specific time (soft ban). When invalid login counter reaches second level, account will be disabled permanently.

8.3.1. Configuration

Brute-force Prevention is configured by VHost. There is following lis of configuration parameters:

brute-force-lock-enabled

boolean

Brute Force Prevention Enabled