[[tigaseExternalComponent]]
= External Component Configuration
:author: Artur Hefczyc <artur.hefczyc@tigase.net>
:version: v2.0, August 2017: Reformatted for v8.0.0.

As for all Tigase components you can load and configure external components via the `config.tdsl` file described in details in the xref:dslConfig[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:

[source,dsl]
-----
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 xref:bindExtHostnames[`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. http://psi-im.org[Psi].

image:images/admin/adminui_ext_add_item_button.png[]

You will be presented with a form which you should fill to configure external component connection details:

image:images/admin/adminui_ext_add_item_form.png[]

* _Domain name_ - external component domain name (`muc.devel.tigase.org`)
* _Domain password_ - password for authentication of the external component connection (`muc-pass`)
* _Connection type_ - `accept` to make component wait `for connection or `connect` force component to connect to the server (`connect`)
* _Port number_ - port on which component should wait for connection or on which it try to connect (`5270`)
* _Remote host_ - host to connect to (`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 https://xmpp.org/extensions/xep-0114.html[XEP-0114: Jabber Component Protocol]
*** `XEP-0225: Component Connections` - for https://xmpp.org/extensions/xep-0225.html[XEP-0225: Component Connections]
** if connection type is `accept`:
*** `Autodetect` - for automatic detection of protocol used by incoming connection _(recommended)_
*** `XEP-0114: Jabber Component Protocol (accept)` - for https://xmpp.org/extensions/xep-0114.html[XEP-0114: Jabber Component Protocol]
*** `XEP-0225: Component Connections` - for https://xmpp.org/extensions/xep-0225.html[XEP-0225: Component Connections]

Additional 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. http://psi-im.org[Psi].