Network Connection Problems and Solutions
Network Connection Problems and Solutions
this is an import from the Network FAQ PDF v1.7 from [1]
Assumptions
MapTool will start via either WebStart or by executing the proper file for your operating system that resides in the ZIP archive or DMG image. If you do not get the MapTool splash screen or the default "Grasslands" background map when you start MapTool, this document will not help you.
Symptoms
When someone else attempts to connect to your server, their MapTool seems to pause for a long time with the Connecting message and then finally times out and gives up. The error message may say “Connection timeout” or it may be something more generic like “Could not load campaign” (which indicates an inability for the network to pass data back and forth).
The server running on the hosting computer is not seen by Internet connection testing tools such as CanYouSeeMe.org. These testing tools should be started after the MapTool server has been started via the File → Start Server... dialog. More discussion of these tools is covered after the next section on terminology and theory of operation.
Background Information
MapTool uses TCP/IP to make a connection from each client to the server. Without going into a lot of nitty-gritty detail about how TCP/IP works, I will provide a short (and amazingly accurate) analogy of TCP/IP using the phone system. The rest of this section can be skipped if you are confident of your knowledge in networking basics and already know the difference between a “switch” and a “router”. However, forum users will expect you to be familiar with the information in this section if you ask for help there. At a minimum you should be familiar with the terminology.
A simple network
The picture below depicts multiple computers on a local area network (LAN). Each computer is labeled with a hostname – a name used to uniquely refer to that particular computer. You can think of these names just like the names of your friends, your family, your employer, and so on: when you need to talk to one of these people, you look up their phone number in the phonebook and then pick up the phone and dial.
In the picture, let's assume that PC1 is the server and PC2 and PC3 are clients. In order for the clients to contact the server, they need some way to locate PC1 on the network. This is the phonebook look up that was discussed in the last paragraph. One look up technique is called "DNS" (Domain Naming Service) and is very common on the Internet. The primary function of DNS is to convert hostnames into IP addresses very similar to the way you use a phonebook to convert a person's name into their phone number. However, if you dial the number of your best friend very often, are you going to have to look it up in the phonebook? Probably not! You probably have it memorized or stored in your local contact list. TCP/IP is the same way: if you know the IP address of a machine you can use that instead of the hostname.
MapTool provides a shortcut to DNS called the RPTools Registry. When you open the File → Connect to Server... window, you'll see a list of MapTool servers that have registered with RPTools.net. This allows a client to just double-click the correct entry in order to attempt a connection. The client will contact the RPTools.net web site and retrieve the IP address of the server. Once it has this information, the client will use the IP address of the server to make their connection. So the IP address is the "phone number" that you use to contact the server. The client now knows how to contact the server and send/receive data. However, the RPTools.net technique is only for connecting to MapTool servers outside your own LAN – on your LAN you should pick a server from the LAN tab. In fact, it's likely that using the RPTools registry will fail even if your server is working fine; this is discussed in more detail later.
Whenever the client wants to send a packet of data to the server, it prepends the IP address and puts it out onto the network. Each machine between the client and server forwards the packet to the next one in the link. In the picture above, there are no intermediate machines since all machines are connected to the same wire, but when communicating over the Internet there will be tens or hundreds of intermediate machines. An example of an intermediate machine is shown in the next picture.
When you call your family or friends, the phone number is all you need to make contact. But if they are at work, you may need to use more than a phone number – you may need an extension number as well. In the terms of TCP/IP, that extension number is the port number that the server allocates when it starts. This port number allows multiple applications on a single machine to be "listening" for incoming phone calls. The default port number for MapTool is 51234. Other default port numbers include 80 for web servers and 25 for email servers. Port numbers less than 1024 are reserved for well-known server applications and those from 1024 to 5000 are reserved for local use, so if you change the MapTool port number, be sure to choose one larger than 5000. In summary, the IP address and the port number uniquely identify an application on the computer and are used to deliver packets between the two computers, the same way that a phone number and extension number uniquely identify a person or department in a company.
When a MapTool server starts it lets other machines on the same network know of its existence. This is evidenced by the clients being able to go to the LAN tab when they choose File → Connect to Server... and see the server appear in the list. This technique is similar to the phone company giving you a new phonebook that has been updated with new contact information every time someone in your nehgiborhood changes their phone number! In the real world that doesn't happen, but in the electronic world it's almost required because things can change so quickly. (It doesn't really work like this, but this is a functional description and not a treatise on the implementation :)).
Connecting outside your own network
When all of the computers, both server and client(s), are on the same network the situation is pretty simple as we discussed above. But what happens when the server is remote from the clients? In this situation, routing the client's phone call through a lot of other machines is required before the phone rings at the server's location. And if you've ever tried to contact the CEO of a company directly, you can be sure that their secretary is going to run interference!
One of the jobs of the CEO's secretary is to filter incoming messages and decide which ones get to the executive and which ones don't. This is why it can be of more importance to have the secretary's ear than the CEO's! In comparison to a network, the router's job is the same as the secretary's.
I'm using the term router pretty loosely here. In this guide, I use the term router to mean any device between your computer and the Internet whose job is to filter network data. The primary goal of a router is to protect your computers from those on the Internet – it doesn't let them succeed in connecting to your computer. Secondary goals are to allow multiple IP addresses within your home while only allocating a single IP address on the Internet. But we're getting ahead of ourselves a little bit...
In the case of MapTool, when a client calls a server, it's possible that the server's router might block that incoming request. In that situation, the client hears a ring-ring on their end, but the MapTool server never knows that the call was even made because the router blocked it. This will be reported as “Connection Failed: timeout” or something similar. In the picture above, any time PC2 or PC3 tries to contact PC1, they have to get through the router first. Most commercial routers have firewall software built into them. Routers that cost thousands of dollars will have more sophisticated firewalls than the "home use" router you bought at the BigBox store, but the goal of filtering traffic remains the same. And that brings us to our next topic...
Port forwarding and UPnP
Most routers, just like most secretaries, can be told that some traffic is more important than other traffic and that it should be routed directly through. Can you imagine how much trouble the CEO would be in if he didn't take his wife's (or her husband's) call in a timely manner? A good secretary can actually figure some of this out on their own. For example, the CEO calls his wife and they chat for a few minutes. When the wife calls back in five or ten minutes, you can bet that the secretary will simply route it straight through. Computer firewalls can be told to do the same thing. This is called port forwarding.
Essentially, when a call to a certain IP address and port number is about to be blocked by the router, it will check its exception list. If the exception list says to go ahead and allow the call to proceed, the router forwards the call to the IP address and port number of the CEO's desk. This is what happens when you have a router sitting between your Internet connection (DSL, cable modem, satellite, dial-up, or any other type) and your home computer(s). The router will act as a firewall and not allow any incoming phone calls unless you've specified a list of exceptions. The actual technique for how to accomplish this varies from router to router, so the MapTool forums recommend that the home user visit [2] and search for their particular router model for instructions.
Note that port forwarding can be turned on and left that way or it can be enabled on the router only when it is going to be used. For security purposes, it is best to only have it turned on when you need it and turn it off when you're done. Note that the router doesn't block outbound calls that the CEO makes; the CEO can pick up the phone and dial his wife without the secretary stopping the call. This is like running a browser and connecting to a web site – the router doesn't get in the way. But if the web site were to try contacting your browser directly, the request would be blocked.
This is a problem for us: we want to run a MapTool server and we want the router to let that traffic through! Because routers (and firewalls) are supposed to be blocking exactly that kind of traffic, we don't have any choice. We must visit that URL given above and figure out how to configure our routers. Unfortunately, not everyone relishes the idea of reprogramming their router the way I do! Yes, hard to believe, but not everyone is a geek. (Geek = cool and trendy computer person, Nerd = not-so-cool and trendy computer person, and Dork = totally un-cool computer-person-wannabe. You see? I told you there was a lot of terminology in this section!)
So there's another technique that can be used: the CEO could explicitly tell the secretary something like, "any calls that come in on extension 80 should be routed directly to my desk." Now the secretary can pass calls directly to the CEO and not worry about needing to filter them. Maybe the CEO is expecting a call from a certain individual and wants to take the call immediately. Or perhaps the CEO has a "private line" that the secretary monitors but allows calls to "ring through". Having such an automated system for your router is called UPnP, short for Universal Plug-n-Play. (An alternative is called NAT-PMP, but they are functionally the same so the second won't be mentioned again.)
If you have turned on this feature on your router, then the MapTool 1.3.b23+ server, or any other program running on your network, can tell the router to allow certain ports through for a limited period of time. You will need to refer to your router manual for instructions on how to verify that this feature is enabled.
Needs Clarification:
NEED A URL REFERENCE FOR THIS.
If this feature is turned on in your router you can try enabling it in MapTool by checking the Use UPnP checkbox in the File → Start a Server... window.
You must not use both port forwarding and UpnP! If you try to use both at the same time, most secretaries will simply become confused and not know what to do at all when a call comes in – you don't want that do you?!
Network Address Translation (NAT)
Unfortunately, many companies don't have enough phone lines for each employee to be on the phone all at the same time. (Well, maybe that's unfortunate. I can think of a few situations where that's not such a bad thing!) When a customer calls the company, they use a single phone number. The switchboard operator for the company will convert the number the customer dialed into the internal number used by the company's phone system (sometimes called a PBX).
The Internet requires such a feature. There are only a certain number of IP addresses that can be used, so network address translation was devised to help prevent them from being used up too quickly. For example, your author has a cable modem at home. Connected to the cable modem is a router. This router is assigned a public IP address by my ISP, but the rest of the computers in the house receive a randomly assigned private network address from the router. Most routers use random IP addresses in the range of 192.168.0.2-192.168.0.100 or something similar. The computers attached to the router don't realize that they are receiving random IP addresses – they just take what they get and are happy with it! You can use MapTool's File → Connection Information... menu option to determine what your private IP address is, as well as the external IP address of your router.
When my laptop makes an outbound connection, the router keeps track of my private IP address so that when the response comes back, it can send the response to my laptop and not to my wife's desktop or the TiVo or the laser printer.
Advanced NAT Scenario
One issue with this technique is that to any computer outside my home the IP address looks the same for every computer inside the house. This is why port forwarding is important. When a call comes in to the router for port 51234, the router forwards it to a preprogrammed private IP address. Using this scheme, can I run multiple MapTool servers on my home network and have different outside computers connect to them? It might appear that the answer is "no" because there's only one "port 51234". However, if a different port number is assigned to each MapTool server, the router can be configured to forward each port to a different private IP address. For example, my laptop, my wife's desktop, and my TiVo are all on the same network (not really, but we can pretend they are for the sake of this example). I could forward port 80 on the router to the TiVo, then when I'm traveling I could find out which shows the TiVo has recorded by visiting port 80. I could forward port 55555 to my laptop (port 51234) and port 55556 to my wife's desktop (port 51234). Notice how the destination port is the same on both, but the outside port numbers are different? This would allow multiple MapTool servers on the internal network to be connected to by different outside computers. This is exactly like having a company with multiple outside extension numbers. When a customer calls the company, the secretary figures out who the call is for and sends it to the right person. The fact that there are two “John Smith” employees doesn't confuse the secretary because the port forwarding as a different extension number for each one.
The last example is probably pretty confusing and there's no shame in going back and reading the last few sentences two or three times. Go ahead... I'll wait.
Basically, that last example says that the router has two phone extensions configured (ports 55555 and 55556) and each one is sent to a different location inside the company. The first goes to my laptop, the other goes to my wife's desktop. But I don't want to have to change the port number in MapTool, so I just leave it 51234.
To use a configuration in which the MapTool port number doesn't change, I can't use UPnP. If I did, and I tried to run MapTool on both my laptop and my wife's machine at the same time, the router couldn't accommodate both of us – only one of us could have extension 51234. So I'd have to reprogram the port forwarding manually on the router. This is also not a good choice if you're going to use the RPTools Registry feature since the port number MapTool will give the MapTool registry is not the one your router will be configured for. Remember: when a player connects to your server, they will get the outside extension number. If you've manually set up port forwarding and used a different internal and external port number then the wrong number will be stored in the registry.
If I was willing to use different ports for MapTool, then I could use UPnP. Because UPnP doesn't require you to reprogram your router, this is the one I recommend. Especially when you consider that you could get a different private IP address every time you power up your computer! (Remember earlier when I said the router will give you a randomly assigned IP address? The truth is that you will probably get the same address, but to be safe you should treat it as though your machine gets a different address at each reboot.) This is a much better solution because if you fill in the RPTools.net Alias field on the File → Start Server... dialog, this port number is saved in the MapTool registry and is the port that other clients will attempt to connect to.
Two Routers and the “Double-NAT” Problem
The big issue with NAT is something called "double-NAT". What if there are two routers between the outside computers and the inside server? It becomes impossible for UPnP to handle this and while the configuration of both routers is possible, often the home user doesn't have control over one of the routers. Sometimes the home user can put one router in “bridged” mode, which essentially turns off the firewall in that router and tells it to pass all connections straight through. This effectively eliminates it from the picture. This is a good choice in cases where your ISP has provided you with equipment and your control over that equipment is limited. In all other cases of double-NAT, running a MapTool server will require a VPN solution. Beyond mentioning the Hamachi program (which is popular on the MapTool forums), further discussion of VPNs is beyond the scope of this document. Be sure to ask on the forums if you have this issue. When enough interest is shown, this document will be updated. (It has happened. See FAQ#12 below for more information.)
It's a two-way street
The last thing to point out is that all communication must be two-way to be useful. Yet the secretary on the client end will always allow incoming data if the client initiated the request in the first place! We talked about this above, when we discussed the overall flow of the network traffic. We said that the secretary doesn't get in the way of outbound calls, only inbound calls. And only the server will have inbound calls so only the server needs to have port forwarding configured.
For example, when you type a URL into a browser, the browser makes the outbound request and the router allows the response to come back in. The same thing will apply to MapTool; if the client sends a packet to the server, the client's router will allow the response to get through. This is one of the security issues in a router; it cannot block traffic that is a result of a request made by an internal source. (This is the primary issue with cross-site scripting attacks, which is when a script embedded on a web page makes a request that the user doesn't know about and then sends the information to another location, also without the user's knowledge or consent! Since the script is operating from inside the company's router, the router cannot know that it should block the traffic.)
In the following section, a series of common MapTool connection problems will be discussed, including the symptoms and possible solutions.