You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

TODO: Move links over to apache infra

The utility of waves is greatly enhanced if they can be federated in the sense that they are shared between users from different organisations, hosted by different service providers across the Internet. This is accomplished by the Apache Wave federation protocol, a server-to-server network protocol between service providers, supporting low-latency, concurrent updates to conversations ("live typing") and domain authentication.

Here are some resources that explain the protocol and show how to run a federated "Wave in a Box" wave server:

Introduction

After you have installed your XMPP server and the Federation extension, you can federate with other Wave servers.

Overview

To get federation working the two servers that are going to talk will need a clear view of each other. That is, each server in the conversation needs to be able to initiate a connection with the other server doing federation, and vise-versa. Not only does that mean that your server needs to be found via DNS, it also means that the correct port to use for federation must be able to be found and used.

A wave server (e.g. the one hosting waves at "initech-corp.com") will attempt to send updates to a remote wave server (e.g. the one hosting waves at "other.com") whenever a wavelet with a remote participant (e.g. "bob@other.com") is updated (I.e. any operation is applied, including AddParticipant?("bob@other.com")). The other case where a wave server will send a message to a remote wave server is to submit a delta on a wave hosted at the remote wave server. The domain name for the remote wave server is taken directly from the participant's ID (e.g. "other.com").

If no existing XMPP connection exists between the XMPP servers to which the wave servers are connected (via the XMPP component protocol), a new connection needs to be established. The connection is established using XMPP hostname resolution (draft-ietf-xmpp-3920bis) and XMPP service discovery (XEP-0030). Where a XMPP server does not offer XMPP service discovery, or the hostname resolution on the domain name fails, a guess is made about where the wave service is available; "wave." is prepended to the the remote domain name.

Connection Establishment

This describes the algorithm by which two Wave servers establish a connection for the purpose of federation. In this description the functionality of the XMPP server and the wave server XMPP component are conflated into "XMPP server". In the description below we trace the possible steps an Initiating Server (IS) takes to connect to some Other Server (OS). The following steps reference draft-ietf-xmpp-3920bis and XMPP service discovery XEP-0030.

  1. Initiating XMPP server (IS) attempts to look up the SRV record(s) for _xmpp-server._tcp.other.com (OS).
  2. If the lookup succeeds, proceed to step 5.
  3. If the lookup fails, attempt an A record lookup for other.com
  4. If the lookup succeeds, proceed to step 5, otherwise go to step 13.
  5. IS connects to the XMPP server OS and initiates XMPP discovery.
  6. If OS supports XMPP discovery, IS enumerates services, one item of which is hopefully "category: collaboration, type: google-wave". The enumerated item is available on a jid, e.g. "waveservice.other.com".
  7. If IS finds the disco record, and the provided jid does not match the hostname of the existing connection, it will attempt to resolve the provided jid via the regular XMPP SRV record lookup e.g. _xmpp-server._tcp.waveservice.other.com or the A record fallback e.g. waveservice.other.com.
  8. If step 7 succeeds, proceed to step 12, otherwise goto step 9.
  9. If OS does not support XMPP discovery, or does not return a discovery item for "google-wave", or the lookup on the discovery item failed, IS will make a guess at a service jid by adding "wave." to the remote domain name, e.g. "wave.other.com".
  10. IS will attempt to resolve the guessed "wave" jid via the regular XMPP SRV record lookup e.g. _xmpp-server._tcp.wave.other.com or the A record fallback e.g. wave.other.com.
  11. If the lookup succeeds, and the IP or port is different to the connection established in 5. above, connect to the new IP/port. If the lookup fails, goto step 13.
  12. IS and OS are ready to establish TLS. Stop.
  13. Failed to establish a connection. Stop.

Background

SRV Settings

In order to expose a federation server, you require SRV records that describe which servers and ports that the incoming connection should use.

The SRV record is analogous to the old MX record for mail servers, that is, it 'points' the incoming query to the correct server, and assigns priorities to different machines. However it contains extra information on top of this basic data.

A typical SRV record takes the form of:

_Service._Protocol.Name TTL Class SRV Priority Weight Port Target

A typical Wave SRV record could be:

_xmpp-server._tcp.example.com. 86400 IN SRV 10 0 5269 wave.example.com.

A server trying to connect to the Wave server for example.com would retrieve this record, and proceed to attempt to connect to wave.example.com on port 5269.

Note you could have several SRV records to specify failover/redundancy or whatever:

{{_xmpp-server._tcp.example.com. 86400 IN SRV 10 50 5269 wave1.example.com.
_xmpp-server._tcp.example.com. 86400 IN SRV 10 50 5269 wave2.example.com.
_xmpp-server._tcp.example.com. 86400 IN SRV 20 0 5269 backup-wave.example.com.}}

A Records

Every 'Target' of an SRV should have an appropriate A record in DNS, so that the server can resolve the name to an IP address. In the example above, you would need to assure that wave.example.com had a valid record, and could be resolved externally.

Ports

An SRV record defines which port the service is available on. For example the following service is accepting connections via port 31423:

_xmpp-server._tcp.example.com. 86400 IN SRV 10 0 31423 wave.example.com.

You can specify any valid port number for your server. This is especially useful as in the diagram below, where a wave server is behind a NAT/Firewall.

In this diagram, you would need to configure the incoming port 31423 (as per our example) on your firewall to pass through to the correct server. The usefulness of this setup is that you would be able to run multiple Wave servers behind a firewall, even for multiple domains, and simply assign each one a unique port:

quote
{{_xmpp-server._tcp.example.com. 86400 IN SRV 10 0 5269 wave.example.com.
_xmpp-server._tcp.anotherexample.com. 86400 IN SRV 10 0 5270 wave.anotherexample.com.
_xmpp-server._tcp.fickleexample.com. 86400 IN SRV 10 0 5271 wave.fickleexample.com.}}
quote

Recommended DNS Configuration

The following DNS records are recommended. If your Wave server provides hosting for the domain <yourdomain> then:

  1. Configure a SRV record for _xmpp-server._tcp.<yourdomain> that points to the port and domain name of your XMPP server.
  2. If your server supports XMPP disco, and the "google-wave" disco item jid is <yourdomain>, you don't need any other records.
  3. If your server supports XMPP disco, and the "google-wave" disco item jid is <some prefix>.<yourdomain>, you should configure an SRV record for _xmpp-server._tcp.<some prefix>.<yourdomain> that points to the port and domain name of your XMPP Wave component server.
  4. If your server does not support XMPP discovery, you will need to configure a SRV record for _xmpp-server._tcp.wave.<yourdomain>.
  5. Using SRV records as described above is the preferred resolution mechanism. If for some reason this does not work for you, DNS A records can be used in place of the SRV records.

Example

Let's presume the following setup, that you are running your XMPP server and Federation extension behind a NAT and are trying to federate with acmewave.com:

  • No labels