The concept of Jabberd transports can be confusing to new Jabberd 2 administrators. The fact that many Jabberd 2 transports rely on legacy Jabberd 1.4 support makes this especially true for administrators who have no experience with Jabberd 1.4. This appendix provides a primer on Jabberd 2 transports by explaining how transports have evolved:
At first glance, this may seem to be more information than a new Jabberd 2 administrator would require; however, understanding legacy transport support in Jabberd 2 requires an understanding of how transports work with the Jabberd 1.4x series server. Note that in this appendix, the term "transport" is applied liberally to mean any external Jabber service.
The Extensible Messaging and Presence Protocol (XMPP): Core draft provides an overview of how transports, known as gateways in XMPP parlance, work with a Jabber server.
Figure A.11.1. Jabber Deployment Diagram (High Level View)*:
PC 2 SVR 2 PC 3
.-----------------. .-----------------. .-----------------.
| | | | | |
| ,---------. | | ,---------. | | ,---------. |
| ,' `. | | ,' `. | | ,' `. |
|( Jabber Client -+-------+- Jabber Server -+-------+- Jabber Client )|
| `. ,' | | `. ,' | | `. ,' |
| `---------' | | `----+----' | | `---------' |
`-----------------' `--------+--------' `-----------------'
|
PC 1 |
.-----------------. .--------+--------.
| | | | | SVR 1
| ,---------. | | ,----+----. |
| ,' `. | | ,' `. |
|( Jabber Client -+-------+- Jabber Server )|
| `. ,' | | `. ,' |
| `---------' | | `----+----' |
`-----------------' | | |
| ,----+----. |
| ,' Foreign `. |
|( IM )|
| `. Gateway ,' |
| `----+----' |
`--------+--------'
|
|
.--------+--------. .-----------------.
| | | | |
| ,----+----. | | ,---------. |
| ,' Foreign `. | | ,' Foreign `. |
|( IM -+-------+- IM )|
| `. System ,' | | `. Client ,' |
| `---------' | | `---------' |
`-----------------' `-----------------'
SVR 3 PC 4
Figure A.11.1. is adapted from XMPP Core Draft
Figure A.11.2. Key to Deployment Diagrams:
Key for Deployment Diagrams
+------------------------------------------------------+
| |
| ,---------. |
| ,' `. |
| ( ) +-------------+ |
| `. ,' TCP/IP Connection |
| `---------' |
| Software Package |
| or Module |
| +-------------------+ |
| .---------------. | | |
| | | +-------------------+ |
| | | | | |
| | | | | |
| | | | | |
| `---------------' +-------------------+ |
| Computer: Configuration |
| PC or Physical File |
| Server (XML) |
| |
+------------------------------------------------------+
Essentially, a transport is a piece of software, which connects to a Jabber server and which allows client communication with a non-Jabber instant messaging system.
Transports for the Jabberd 1.4x series server are generally supplied as shared object files that are executed and run by the Jabber 1.4x server. Originally, these shared object files were loaded by the main Jabberd 1.4x process, and configuration for each transport was contained in the main Jabberd 1.4x configuration file. The diagram below shows how a Jabber 1.4x server might load and run a transport called yahoo.
Figure A.11.3. Jabberd 1.4x Server Running a Transport Internally:
.-----------------.
| |
| ,---------. |
| ,' `. |
|( Jabber Server )|
| `. ,' |
| `----+----' |
`--------+--------'
|
|
.-----------------. .--------+--------. +----------------------+
| | | | | | jabber.xml |
| ,---------. | | ,---------. | +----------------------+
| ,' `. | | ,' Jabber `. | | |
|( Jabber Client -+-------+- 1.4x )|.......| <configure server> |
| `. ,' | | `. Server ,' | | |
| `---------' | | `----+----' | | <load yahoo.so> |
`-----------------' | | | | <configure yahoo tx> |
`--------+--------' | |
| +----------------------+
|
.--------+--------.
| | |
| ,----+----. |
| ,' Yahoo `. |
|( IM )|
| `. System ,' |
| `---------' |
`-----------------'
Note that in these diagrams, the XML configuration files have been extremely simplified. The abbreviation "tx" stands for "transport".
The problem with the configuration in Figure 11.3. is that the main server process becomes dependent on the transport. That is, a problem with the transport can bring the entire Jabberd 1.4x server down. To address this issue, the 1.4x series Jabberd server supports what I call linked configuration files.
The idea behind linked configuration files is that the main Jabberd server does not run any of the transports. Rather, each additional transport is run in a separate Jabberd 1.4x process. For each transport, the main Jabberd configuration file contains a section that identifies an external service. Service information includes an ID for the service, an IP address and port to connect to the service, and a shared secret used to authenticate the service.
Each transport exists as a separate Jabberd 1.4x process with its own configuration file. The configuration file for a transport contains the service information found in the main configuration file (ID, address, port and secret) in addition to configuration for the transport itself. Figure A.11.4. continues with the example above and shows how a separate Jabberd 1.4x process could be used to run a transport.
Figure A.11.4. Jabberd 1.4x Server Running a Transport as a Separate Process:
.-----------------.
| |
| ,---------. |
| ,' `. |
|( Jabber Server )|
| `. ,' |
| `----+----' | +----------------------+
`--------+--------' | jabber.xml |
| +----------------------+
| | |
.-----------------. .--------+--------. | <configure server> |
| | | | | | |
| ,---------. | | ,---------. | | <service id=yahoo> |
| ,' `. | | ,' Jabber `. | | <ip> |
|( Jabber Client -+-------+- 1.4x )|.......| <port> |
| `. ,' | | `. Server ,' | | <secret> |
| `---------' | | `----+----' | | |
`-----------------' | | | +----------------------+
| ,----+----. |
| ,' Jabber `. | +----------------------+
|( 1.4x )|.......| yahoo.xml |
| `. Server ,' | +----------------------+
| `----+----' | | |
| | | | <service id=yahoo> |
`--------+--------' | <ip> |
| | <port> |
| | <secret> |
.--------+--------. | |
| | | | <load yahoo.so> |
| ,----+----. | | <configure yahoo tx> |
| ,' Yahoo `. | | |
|( IM )| +----------------------+
| `. System ,' |
| `---------' |
`-----------------'
The important thing to note in the above diagram is that the Jabberd 1.4x process running the transport does not make any client connections. All client connections are handled by the main Jabberd 1.4x server. The Jabberd 1.4x process handling the transport connects directly to the main Jabberd 1.4x server.
The second thing to notice is that the Jabberd 1.4x process running the transport uses an abbreviated XML configuration file. This configuration file specifies a connection to the main Jabberd 1.4x server, it loads the transport shared object, and it configures the transport.
Jabberd 2 provides backwards compatibility for Jabberd 1.4x compatible transports. Jabberd 2 accomplishes this legacy support by supporting transports that are run within a linked Jabberd 1.4x process. Thus, Jabberd 2 can connect to a transport run as in the figure above.
Configuration for a Jabberd 2 transport running within a Jabberd 1.4x process is nearly identical to what the configuration would be if that transport were connecting to a Jabberd 1.4x server. The main differences are that for Jabberd 2, all transports connect to the router on port 5347, and all share the same secret. Figure A.11.5. shows how a Jabberd 2 server can connect with a transport running within a Jabberd 1.4x process.
Figure A.11.5. Jabberd 2 Server Running a Transport as a Separate Jabberd 1.4x Process:
.-----------------.
| |
| ,---------. |
| ,' `. |
|( Jabber Server )|
| `. ,' | +----------------------+
| `----+----' | | router.xml |
`--------+--------' +----------------------+
| | |
| | <configure router> |
.-----------------. .--------+--------. | |
| | | | | | <secret> |
| ,---------. | | ,---------. | | |
| ,' `. | | ,' Jabber `. | | <alias name= |
|( Jabber Client -+-------+- 2x )|.......| yahoo.domain.com |
| `. ,' | | `. Server ,' | | target=yahoo> |
| `---------' | | `----+----' | | |
`-----------------' | | | +----------------------+
| ,----+----. |
| ,' Jabber `. | +----------------------+
|( 1.4x )|.......| yahoo.xml |
| `. Server ,' | +----------------------+
| `----+----' | | |
| | | | <service id=yahoo> |
`--------+--------' | <ip> |
| | <port> |
| | <secret> |
.--------+--------. | |
| | | | <load yahoo.so> |
| ,----+----. | | <configure yahoo tx> |
| ,' Yahoo `. | | |
|( IM )| +----------------------+
| `. System ,' |
| `---------' |
`-----------------'
Note again that the Jabberd 1.4x process running the transport does not connect to clients. It connects with the router and therefore does not need access to the client ports of 5222 and 5223. Thus, the transport running on the Jabberd 1.4x process can run side-by-side with the Jabberd 2 server. Moreover, the Jabberd 2 server can run side-by-side with multiple Jabberd 1.4x processes running various transports.
Note also that the Jabberd 2 server does not run the transport. The transport is started and run separately in a Jabberd 1.4x process, and it connects to the Jabberd 2 server over a TCP connection.
Section 5.8 of this guide explains how to use Jabberd 1.4x to provide transports for Jabberd 2.
The Jabber Component Runtime provides a wrapper for Jabber 1.4x compatible transports. Instead of running a legacy transport within a Jabberd 1.4x process, JCR can be used to create a binary file that runs a transport. Essentially, the JCR wrapper provides the services that a separate Jabberd 1.4x process would provide for a transport. Figure A.11.6. shows how Jabberd 2 can connect to a JCR wrapper running a transport.
Figure A.11.6. Jabberd 2 Server Running a Transport Using JCR:
.-----------------.
| |
| ,---------. |
| ,' `. |
|( Jabber Server )|
| `. ,' |
| `----+----' |
`--------+--------'
|
| +----------------------+
.-----------------. .--------+--------. | router.xml |
| | | | | +----------------------+
| ,---------. | | ,---------. | | |
| ,' `. | | ,' Jabber `. | | <configure router> |
|( Jabber Client -+-------+- 2x )|.......| |
| `. ,' | | `. Server ,' | | <secret> |
| `---------' | | `----+----' | | |
`-----------------' | | | +----------------------+
| ,----+----. |
| ,' JCR `. | +----------------------+
|( Yahoo )|.......| yahoo_jcr.xml |
| `. Binary ,' | +----------------------+
| `----+----' | | |
| | | | <secret> |
`--------+--------' | |
| | <configure yahoo tx> |
| | |
.--------+--------. +----------------------+
| | |
| ,----+----. |
| ,' Yahoo `. |
|( IM )|
| `. System ,' |
| `---------' |
`-----------------'
As is true for a transport running within a Jabberd 1.4x process, a transport running within a JCR wrapper runs separately from the Jabberd 2 server. Section 5.9 of this guide explains how to run a transport within a JCR wrapper.
Some transports, especially newer ones, can run natively with the Jabberd 2 server. Python MSN-Transport is an example of a transport that can run natively with Jabberd 2. These newer transports connect to the Jabberd 2 server much in the same way that a JCR-wrapped transport does.
Some older transports do not support discovery. Discovery, or disco, is the capability of advertising service availability to clients. Clients see this availability when browsing services on a Jabber server. For a transport that does not support discovery, an entry must be made in sm.xml to advertise that transport's availability. See the Static service list section of sm.xml for an example entry for a transport that does not support discovery.
To recap the above discussion, administrators have three options for running transports with Jabberd 2:
Running transports within Jabberd 1.4x processes is the most universal option because at the time of writing, many transports will only run within a Jabberd 1.4x process.
Running a transport within a Jabberd 1.4x process means that a Jabberd 1.4x process — separate from the Jabberd 2 processes — will provide a transport service. To accomplish this, you will need to download, compile and install Jabberd 1.4x, in addition to downloading and compiling the transport.
Instead of running Jabberd 1.4x with a full-blown configuration file, the Jabberd 1.4x process will be run with a minimized configuration file that is designed to load the transport, configure the transport, and connect to the router to provide the service. The configuration file for the Jabberd 1.4x process should contain the following elements (in addition to configuration details for the transport itself):
router IP address and portsecret shared by the router component (found in router.xml)router.xml)See Section 5.8 for details on how to set up such a configuration file for a Jabberd 1.4x process running a transport. Note that many transports contain an example for a linked configuration file. Such an example forms the basis for a Jabberd 1.4x configuration file that can be used to run a transport under Jabberd 1.4x with Jabberd 2.
Running a transport within the JCR wrapper means that a dedicated binary will run the transport. To accomplish this, you will need to download JCR and the transport. Following the instructions included with JCR, you will first build JCR and then compile it against the transport to create a binary that will run the transport. The JCR binary will then be run as a separate process with its own configuration file, and this configuration file will specify connection with the router component, including the shared secret. See Section 5.9 and the JCR Home Page for more information about running a transport with JCR.
Running a transport natively means that the transport is run as its own standalone process with its own configuration file. A natively-run transport will connect with the router component of Jabberd 2, and thus, the configuration file must contain connection details for the router, including the shared secret.
2004/08/26 01:31 PST
Most of this text is also usable for people running ejabberd.
© 2003 Will Kamishlian and Robert Norris
This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/1.0/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
|
|
|
|
|