Tigase can connect to external components, this guide will show you how this can be accomplished.
Configuration follows the same standards as all other components. It is also much more powerful as a single Tigase instance can control many TCP/IP ports and many external components on each port and even allows for multiple connections for the same component. It supports both XEP-0114 and XEP-0225 with protocol auto-detection mechanisms. Protocols are pluggable so more protocols can be supported or custom extensions to existing protocols can be added.
The implementation also supports a scripting API and new domains with passwords can be added at run-time using ad-hoc commands. New scripts can be loaded to even further control all connected external components.
Pages in this guide describe in details all the administration aspects of setting up and managing external components.
As for all Tigase components you can load and configure external components via the config.tdsl
file described in details in the DSL configuration section. This document describes how to enable the component and set the initial configuration to accept or initiate connections for an external component.
First thing to do is to specify the component class and the component name which must be unique within the Tigase installation. The most commonly name used is ext
and the class is tigase.server.ext.ComponentProtocol
(class doesn’t have to be specified when using default name).
The following line in the config.tdsl
will load the component during the server startup time:
ext (class: tigase.server.ext.ComponentProtocol) {}
While this would load the component, without any additional configurations provided, the component would be practically useless. It is necessary to configure the virtual host domains of the external component during run-time via ad-hoc commands to make use of this component.
You may additionally configure the bind-ext-hostnames
property.
To configure external component connections using Admin UI you need to open Admin UI web page (if you are logged in the same computer on which Tigase XMPP Server is running by default it should be available at http://localhost:8080/admin/).
Then you should click on Configuration
on the left side of the Admin UI web page and then select Add new item
on ext
component or by execution corresponding ad-hoc command on ext
component using ad-hoc capable XMPP client, ie. Psi.
You will be presented with a form which you should fill to configure external component connection details:
muc.devel.tigase.org
)muc-pass
)accept
to make component wait for connection or `connect
force component to connect to the server (connect
)5270
)devel.tigase.org
) (may be left blank if component will only accept connections)Protocol - id of protocol used for establishing connection
if connection type is connect
:
XEP-0114: Jabber Component Protocol (accept)
- for XEP-0114: Jabber Component ProtocolXEP-0225: Component Connections
- for XEP-0225: Component Connectionsif connection type is accept
:
Autodetect
- for automatic detection of protocol used by incoming connection (recommended)XEP-0114: Jabber Component Protocol (accept)
- for XEP-0114: Jabber Component ProtocolXEP-0225: Component Connections
- for XEP-0225: Component ConnectionsAdditional options may be left with defaults.
Later on if you would like to modify this values, you can do that using Admin UI by clicking on Configuration
and Remove an item
or Update item configuration
at ext
component or by execution corresponding ad-hoc commands on ext
component using ad-hoc capable XMPP client, ie. Psi.
There are cases when you want to deploy one or more Tigase components separately from the main server, or perhaps you want to run some Tigase components connecting to a different XMPP server, or perhaps you work on a component and you do not want to restart the main server every time you make a change.
There is a way to run the Tigase server in external component mode. In fact you can run any of Tigase’s components as an external component and connect them to the main XMPP server either via XEP-0114 or XEP-0225 connection.
Let’s look at the examples…
When you are using Tigase server 8.0.0 or newer in the "external component mode" while using shared default "user repository" and you have main server also running Tigase XMPP Server 8.0.0 or newer, then you can benefit from the remote management of the component connections from the main server. To use that, you need to enable external component and external component manager on the main server by adding following line to the config file:
'ext' () {} 'ext-man' () {}
With that in place you can use Admin UI or ad-hoc commands available at ext-man
component of the main server to configure connection details of the servers running in the component
mode.
In Admin UI you click on Configuration
section and select Add new item
at the ext-man
component, which will present you with a following form to fill in external component connectivity details:
A few assumptions:
muc.devel.tigase.org
and password muc-pass
5270
.There is a special configuration type for this case which simplifies setting needed to run Tigase as an external component:
'config-type' = 'component'
Knowing that we can now create simple configuration file for Tigase XMPP Server:
admins = [ 'admin@devel.tigase.org' ] 'config-type' = 'component' debug = [ 'server' ] 'virtual-hosts' = [ 'devel.tigase.org' ] dataSource { default () { uri = 'master_server_default_database_url' } } userRepository { default () {} } authRepository { default () {} } muc (class: tigase.muc.MUCComponent) {} ext () { }
where master_server_default_database_url
is the same URL as the one used on the main server for default data source.
With that in place we can use ad-hoc commands or Admin UI on the main server to configure Tigase XMPP Server to accept external component connections and to connect from the external component to the master server.
Adding external component connection settings to the manager (ext-man) using Admin UI.
You need to pass:
muc.devel.tigase.org
)muc-pass
)accept
to make component wait for connection or connect
force component to connect to the server (`connect)5270
)devel.tigase.org
)Protocol - id of protocol used for establishing connection
XEP-0114: Jabber Component Protocol (accept)
- establish connection using XEP-0114: Jabber Component ProtocolXEP-0225: Component Connections
- establish connection using XEP-0225: Component ConnectionsAdditional options may be left with defaults.
Suppose you want to run more than one component as an external components within one Tigase instance. Let’s add another - PubSub component to the configuration above and see how to set it up.
The most straightforward way is just to add another component to the server running in the component mode for the component domain
admins = [ 'admin@devel.tigase.org' ] 'config-type' = 'component' debug = [ 'server' ] 'virtual-hosts' = [ 'devel.tigase.org' ] dataSource { default () { uri = 'jdbc:derby:/tigasedb' } } userRepository { default () {} } authRepository { default () {} } muc (class: tigase.muc.MUCComponent) {} pubsub (class: tigase.pubsub.PubSubComponent) {} ext () {}
and then to add new connection domain to the main server external component settings and to the external component manager settings. You basically do the same thing as you did while adding only MUC component as the external component.
Please note however that we are opening two connections to the same server. This can waste resources and over-complicate the system. For example, what if we want to run even more components? Opening a separate connection for each component is a tad overkill.
In fact there is a way to reuse the same connection for all component domains running as an external component. The property bind-ext-hostnames
contains a comma separated list of all hostnames (external domains) which should reuse the existing connection.
There is one catch however. Since you are reusing connections (hostname binding is defined in XEP-0225 only), you must use this protocol for the functionality.
Here is an example configuration with a single connection over the XEP-0225 protocol used by both external domains:
admins = [ 'admin@devel.tigase.org' ] 'bind-ext-hostnames' = [ 'pubsub.devel.tigase.org' ] 'config-type' = 'component' debug = [ 'server' ] 'virtual-hosts' = [ 'devel.tigase.org' ] dataSource { default () { uri = 'jdbc:derby:/tigasedb' } } ext () { } userRepository { default () {} } authRepository { default () {} } muc (class: tigase.muc.MUCComponent) {} pubsub (class: tigase.pubsub.PubSubComponent) {}
With this configuration you do not need to configure entries in ext-man
for PubSub component, only for MUC component but you need to user client
as the value for protocol field.
A few assumptions:
muc.devel.tigase.org
and password muc-pass
5270
.There is a special configuration type for this case which simplifies setting needed to run Tigase as an external component:
'config-type' = 'component'
This generates a configuration for Tigase with only one component loaded by default - the component used for external component connection. If you use this configuration type, your config.tdsl
file may look like this:
admins = [ 'admin@devel.tigase.org' ] 'config-type' = 'component' debug = [ 'server' ] 'virtual-hosts' = [ 'devel.tigase.org' ] dataSource { default () { uri = 'jdbc:derby:/tigasedb' } } userRepository { default () {} } authRepository { default () {} } muc (class: tigase.muc.MUCComponent) {} ext () { }
To make this new instance connect to the Tigase XMPP Server, you need to create one more file with external connection configuration at etc/externalComponentItems
which will be loaded to the local database and then removed.
muc.devel.tigase.org:muc-pass:connect:5270:devel.tigase.org:accept
While loading configuration from etc/externalComponentItems
file is supported, we recommend usage of shared database if possible. In future this method may be deprecated.
Suppose you want to run more than one component as an external components within one Tigase instance. Let’s add another - PubSub component to the configuration above and see how to set it up.
The most straightforward way is just to add another external component connection to the main server for the component domain using Admin UI or ad-hoc command on the main server.
Then we can use following configuration on the server running in the component
mode:
admins = [ 'admin@devel.tigase.org' ] 'config-type' = 'component' debug = [ 'server' ] 'virtual-hosts' = [ 'devel.tigase.org' ] dataSource { default () { uri = 'jdbc:derby:/tigasedb' } } userRepository { default () {} } authRepository { default () {} } muc (class: tigase.muc.MUCComponent) {} pubsub (class: tigase.pubsub.PubSubComponent) {} ext () { }
and we need to create a file with configuration for external component connection which will be loaded to the internal database:
muc.devel.tigase.org:muc-pass:connect:5270:devel.tigase.org:accept pubsub.devel.tigase.org:pubsub-pass:connect:5270:devel.tigase.org:accept
Please note however that we are opening two connections to the same server. This can waste resources and over-complicate the system. For example, what if we want to run even more components? Opening a separate connection for each component is a tad overkill.
In fact there is a way to reuse the same connection for all component domains running as an external component. The property bind-ext-hostnames
contains a comma separated list of all hostnames (external domains) which should reuse the existing connection.
There is one catch however. Since you are reusing connections (hostname binding is defined in XEP-0225 only), you must use this protocol for the functionality.
Here is an example configuration with a single connection over the XEP-0225 protocol used by both external domains:
admins = [ 'admin@devel.tigase.org' ] 'bind-ext-hostnames' = [ 'pubsub.devel.tigase.org' ] 'config-type' = 'component' debug = [ 'server' ] 'virtual-hosts' = [ 'devel.tigase.org' ] dataSource { default () { uri = 'jdbc:derby:/tigasedb' } } ext () { } userRepository { default () {} } authRepository { default () {} } muc (class: tigase.muc.MUCComponent) {} pubsub (class: tigase.pubsub.PubSubComponent) {}
and example of the external connections configuration file:
muc.devel.tigase.org:muc-pass:connect:5270:devel.tigase.org:client