NOTE: December 23, 2009: The images are slightly out of date, and configuration for X11 shared apps need writing.

This article describes how to set up the Open Wonderland server to run behind a firewall or NAT system. The Wonderland server requires a fixed public address, as well as a number of TCP and UDP ports to operate properly. If you are trying to run the Wonderland server behind NAT or a firewall, you will need to configure your NAT or firewall so these ports are mapped to your Wonderland server. You will also need to configure the Wonderland server to use a fixed range of ports for its various operations.

Prerequisities#

This article assumes you have already installed a copy of Open Wonderland v0.5 as described here, and have a basic working knowledge of networking and Wonderland. You should also be familiar with the Open Wonderland Web-Based Administration UI.

To run a Wonderland server, you must have a fixed, public IP address to which clients connect. This means that the Wonderland server will not work properly on a machine with a dynamic IP address. If you do not have a fixed IP address, you may look into a number of Dynamic DNS services to provide name resolution for your machine.

Once you have a fixed IP, you will likely setup a firewall or NAT. If you are behind a firewall, the process will involve opening up the key ports to the Wonderland server. If you have a NAT system, you will also need to map your public IP address to the machine behind the NAT which is running the Wonderland server.

Open Wonderland uses a number of different communication mechanisms and protocols (refer to the figure above):

1. Darkstar communication is used for the majority of updates such as login, positioning your avatar, etc.
2. jVoiceBridge uses the standard SIP and RTP protocols for sending the voice data from the server to the client
3. Wonderland uses a peer-to-peer protocol for X11 Application Sharing (Note: X11 Application Sharing is not yet available in the v0.5 developer releases).

Each protocol requires different firewall and NAT strategies, so we will discuss each in turn below.

Getting started#

To set up a Wonderland server behind a NAT or firewall, you will need to do two basic things.

1. First, you will need to configure your NAT router or firewall so that when a request is made to one of the ports that Wonderland uses, it is redirected to the Wonderland server.
2. Second, you will need to configure the Wonderland server so that it knows about your NAT or firewall settings, and uses a appropriate public addresses and port ranges.

Below, we will describe what port ranges need to be mapped on your router or firewall. Please consult your router or firewall documentation for the specifics of how to map ports on your device.

Darkstar Server Communication#

The main communication protocol for Wonderland is the one used by the Darkstar gaming middleware layer. This is a proprietary, TCP/IP-based protocol that uses a single port, which by default is:

TCP port 1139

Forwarding this port should be pretty simple: for a firewall, simply open up TCP port 1139 for incoming connections; for a NAT, map the public IP address port 1139 to the internal machine's port 1139.

You can also change the port that the Wonderland server uses by default in the Open Wonderland Web-Based Administration UI, as follows:

1. Run your Open Wonderland server using the ant run-server command.
2. In a web browser, launch the Wonderland Web-based Administration UI by visiting http://<host name>:<port>/wonderland-web-front/admin where <host name> is the host and domain name of your server machine (e.g. localhost) and <port> is the port on which the server is registered, most often port 8080.
3. Click on the Server Status link on the left-hand side of the UI.
4. On the Darkstar Server row, under the Actions header, click the edit link.
5. Replace 1139 with 12345 in the property line with name sgs.port in the left-hand column.
6. Click the Save button.
7. Click the restart link on the Darkstar Server row under the Actions header to restart the Darkstar server with the new port.

This changes the TCP/IP port upon which the Darkstar server communicates to 12345. While editing the property, your window should look like the following:

The Voice Bridge (jVoiceBridge)#

jVoiceBridge uses the standard SIP and RTP protocols to transmit voice data from the Wonderland server to the various clients. jVoiceBridge uses UDP for communications, which can make it more complicated to pass through firewalls. jVoiceBridge uses a single UDP port for all control data, and an additional two UDP ports per call connected.

The UDP control port is used by SIP, and by default is:

UDP port 5060

jVoicebridge sends both SIP and STUN messages on this port. Some firewalls may be configured to detect and block non-SIP Traffic to this port. If this presents a problem, you may configure the jVoiceBridge to use a different UDP control port, as follows:

1. Run your Open Wonderland server using the ant run-server command.
2. In a web browser, launch the Wonderland Web-based Administration UI by visiting http://<host name>:<port>/wonderland-web-front/admin where <host name> is the host and domain name of your server machine (e.g. localhost) and <port> is the port on which the server is registered, most often port 8080.
3. Click on the Server Status link on the left-hand side of the UI.
4. On the Voice Bridge row, under the Actions header, click the edit link.
5. Replace 5060 with your new SIP UDP control port in the property line with name voicebridge.sip.port in the left-hand column.
6. Click the Save button.
7. Click the restart link on the Voice Bridge row under the Actions header to restart the Voice bridge with the new port.

In addition, jVoiceBridge uses two consecutive UDP ports per call. So to support 100 calls, you will need to open 200 ports on your firewall or NAT. You can control the UDP port range used by jVoiceBridge by editing the properties as follows:

1. Run your Open Wonderland server using the ant run-server command.
2. In a web browser, launch the Wonderland Web-based Administration UI by visiting http://<host name>:<port>/wonderland-web-front/admin where <host name> is the host and domain name of your server machine (e.g. localhost) and <port> is the port on which the server is registered, most often port 8080.
3. Click on the Server Status link on the left-hand side of the UI.
4. On the Voice Bridge row, under the Actions header, click the edit link.
5. On the last blank line, enter voicebridge.first.rtp.port in the left-hand column and 10000 in the right-hand column.
6. Click the Add Property button.
7. On the (new) last blank line, enter voicebridge.last.rtp.port in the left-hand column and 10200 in the right-hand column.
8. Click the Add Property button.
9. Click the Save button.
10. Click the restart link on the Voice Bridge row under the Actions header to restart the Voice bridge with the new port.

This will restrict the voice bridge to use the UDP ports from 10000 - 10200 for voice traffic. While editing the property, your window should look like the following. Note that after you click on the Add Property button, your new property entry gets sorted into the list.

Configuring jVoiceBridge for a NAT requires one more piece of information: the public address of the NAT router. To work through a NAT you will need to map the public address and SIP port to port 5060 on the jVoiceBridge server (refer to the figure below). You will also need to map a range of UDP ports to the UDP port range you selected above. Note that the public port numbers do not need to match the internal ports, but there must be a 1-to-1 mapping between the number of public ports and the number of internal ports.

Once you have configured the external address, edit the jVoiceBridge properties (as done above) to set the following:

Property Name	Value
wonderland.local.hostAddress	my.host.private
voicebridge.server.public.address	my.host.public
voicebridge.server.public.sip.port	5060

Where my.host.private is the private (internal) IP address of the Wonderland server and my.host.public is its public (external) IP address.

---

This material is distributed under the GNU General Public License Version 2