TODO: Move links over to apache infra, XMPP instructions still up to date?Apache infra. Explain server.federation.config.

Introduction

Okay, so now you have WIAB up and running on your laptop. You can successfully login and talk to yourself. Now you're getting the urge to talk to other people on other Wave servers. In order to do this you need to Federate.

...

1. A domain name
2. An ssl certificate from a trusted source (in this case, we use StartSSL) (Recommended, but not necessary whilst you test federation)
3. An XMPP server

Most of the instructions for setting up these things are found in the following child pages:

• Certificates
• Openfire Installation
• Prosody Installation

This document will walk you through setting up federation. With the exception of the configuration script, the instructions will be OS agnostic.

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.

STOP.

IF YOU ARE JUST TRYING TO SETUP FEDERATION ON YOUR SERVER FOLLOW THE LINKS ABOVE. IF YOU HAVE A 'SPECIAL' SETUP, OR WANT TO UNDERSTAND HOW IT WORKS, YOU MAY CONTINUE BELOW THIS LINE.

-------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------

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

...

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

Anchor
background 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.

...

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:

Image RemovedImage Added

We will also presume that the wave XMPP service is running at wave.example.com.

...

$ ./run-server.sh
.
.
.
Aug 26, 2009 7:02:47 PM org.waveprotocol.wave.examples.fedone.federation.xmpp.WaveXmppComponent processPacket
INFO: received XMPP packet:

<message type="normal" id="4191-2" from="wave.acmewave.com" to="wave.example.com">
<received xmlns="urn:xmpp:receipts"/>
</message>
Aug 26, 2009 7:02:47 PM org.waveprotocol.wave.examples.fedone.federation.xmpp.WaveXmppComponent processMessageReceipt
INFO: got ping response from acmewave.com

<message type="normal" id="4191-2" from="wave.acmewave.com" to="wave.example.com">
<received xmlns="urn:xmpp:receipts"/>
</message>

Chatting

To chat you can now go back and run the client:

$ ./run-client-console.sh <username>

And from From within the client create a new wave and add a participant from another federated server:

/new
/open 0
/add thorogood@acmewave.com

If that user is available they can now chat with you. Server details and times that people are available are posted to the wave-protocoldev@incubator.apache.org mailing list. Post yours too and help test federation.TODO: console client still available? Change mailing list to apache-dev?