Basic configuration options

As for all Tigase components you can load it and configure it via init.properties file described in details in another guide. This document describes how to load 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. Following 2 lines in the init.properties will load the component during the server startup time:

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

While this would load the component there is no additional configuration provided to the component would be practically useless. It is possible to add necessary parameters (external domains, passwords) during run-time via ad-hoc commands but this is generally a good practise to provide some initial parameters in the configuration file too. There are two additional properties used for setting initial configuration for external components connections: --external and --bind-ext-hostnames. These two properties are very well described on page under the given links, therefore I will focus on practical and working examples here.

Simple case

The most common scenario is to connect an external component which works for a specific, given domain to the main server. The component authenticates with a defined password and the external component connects to a TCP/IP port the server listens on. For example lat's say our server works for a virtual domain: devel.tigase.org. We want it to listen on port 5270 for incoming connections from an external component working for a domain: muc.devel.tigase.org. The authentication password for the domain is muc-secret. For such a scenario we need 3 lines in the init.properties file:

--comp-name-1 = ext
--comp-class-1 = tigase.server.ext.ComponentProtocol
--external = muc.devel.tigase.org:muc-secret:listen:5270

More external components/domains

Suppose you want to connect more than one external component. Let's say you want to connect PubSub and MSN components to the Tigase server as well. In such a case you don't have to open another port on the server. All the components can connect to the same port. Of course each of the components connect for a different domain and probably should use a different password. Let's say then that we want the Tigase server accept two more domains with corresponding passwords: (pubsub.devel.tigase.org:pubsub_pass) and (msn.devel.tigase.org:msn_pass). Your counfiguration properties should look like this:

--comp-name-1 = ext
--comp-class-1 = tigase.server.ext.ComponentProtocol
--external = muc.devel.tigase.org:muc-secret:listen:5270, \
    pubsub.devel.tigase.org:pubsub_pass, \
    msn.devel.tigase.org:msn_pass

Please note, the --external property with value should be written in a single line. Above example has split the line for readibility.

More TCP/IP ports

You can make the Tigase to listen on more than one TCP/IP port for incoming external component connections. Please be aware however that there is no way, currently to bind an external component to a particular port. If the Tigase listens on two or more ports it accepts any external component on any of the ports. Therefore there is no practical reason for opening more than one port. However, if for some reason you need Tigase to listen on more ports then this is an example configuration:

--comp-name-1 = ext
--comp-class-1 = tigase.server.ext.ComponentProtocol
--external = muc.devel.tigase.org:muc-secret:listen:5270, \
   pubsub.devel.tigase.org:pubsub_pass:listen:5271, \
   msn.devel.tigase.org:msn_pass:listen:5272

Please note, the --external property with value should be written in a single line. Above example has split the line for readibility. Above setting sets three TCP/IP ports to listen on: 5270, 5271 and 5272. It also specifies 3 different external domains with passwords which are accepted by the Tigase. Even though each port is specified with conjunction with a domain they are not bound together in any way. Any of specified domains can connect through any of specified ports.

Outgoing connections

The Tigase server can, not only, accept connections from external components, it can also open connections to external components. To make the Tigase connect to external component you have to change 'listen' parameter to 'connect' and of course you have to tell where to connect - the address of the external component:

--comp-name-1 = ext
--comp-class-1 = tigase.server.ext.ComponentProtocol
--external = devel.tigase.org:muc-secret:connect:5270:muc.devel.tigase.org

Assuming the MUC component listens on the port '5270' at the DNS address: 'muc.devel.tigase.org' the Tigase will connect to the component. You can of course set as many as you need external components to which you want the Tigase to connect to:

--comp-name-1 = ext
--comp-class-1 = tigase.server.ext.ComponentProtocol
--external = devel.tigase.org:mucsecret:connect:5270:muc.devel.tigase.org, \
  devel.tigase.org:pubsub_pass:connect:5271:pubsub.devel.tigase.org, \
  devel.tigase.org:msn_pass:connect:5272:msn.devel.tigase.org

If external components run on a separate machines you can of course us the same port number for each of them.

Specifying protocol

The last parameter you can set for the external component/domain is a protocol which should be used for the connection. At the moment the Tigase server supports two protocols defined in XEP-0114 and XEP-0225 and possibly in the future it may support more. You don't have to specify a protocol if you setup a connection in 'listen' mode as the server automatically detects a protocol which is used in incoming connections. You can, however specify the protocol which is used for outgoing connections. You have to add one more parameter to the connection string. There are two possibilities:

1. 'accept' which is an identifier for protocol defined in XEP-0114 (and is a default if you do not specify anything)
2. 'client' which is identifier for protocol defined in XEP-0225 and is based on the client-to-server protocol.

An example configuration with protocol specified:

--comp-name-1 = ext
--comp-class-1 = tigase.server.ext.ComponentProtocol
--external = devel.tigase.org:mucsecret:connect:5270:muc.devel.tigase.org:accept, \
  devel.tigase.org:pubsub_pass:connect:5270:pubsub.devel.tigase.org:client

It defines two outgoing connections to external protocols, the first uses XEP-0114 protocol and the second uses XEP-0225.