Connection failures.

These have been the bane of many a project, not just Open Cobalt, however it affects us too. I worked through some just today with Kenneth to determine if two Cobalt instances couldn't connect together, or it was just firewalls playing stupid. In the description below, anything in this sort of text should not be typed, but symbolises a prompt for information. Entries like <this> symbolise a single named key to hit on the keyboard, like the <Enter> key. Please, don't type the seven separate characters < e n t e r >. You'd be surprised how many people have done just that. These instructions may duplicate information already out there.

When checking firewalls, remember to check your local computer for any running firewalls. Machines booting Windows have a firewall in place by default, and Microsoft recommends strongly against disabling it. Linux machines typically use an iptables-based firewall, if one was ever installed. I can't say what Mac OS X machines use, as I don't have any Mac OS X experience. A simple set of instructions to configure the Windows or Mac OS X  firewall are mentioned in the Troubleshooting Cobalt document elsewhere.

In addition, check whatever device you're connected to the Internet with; for home users this is often some sort of modem or router device, usually with its own firewall. Business users wanting to run Open Cobalt on the business network should talk to their technical/network support about tcp traffic on port 6900. If you are the technical support, then you should know what I mean. Other ports used by Open Cobalt are described in the Network Usage document.

To test the connection between two computers on the port that Open Cobalt would normally communicate on, take:

• two Linux computers (A pair of Macintosh computers would do if you could find netcat). I'll call the two computers harry and percy.
• a running Skype/IRC/Messenger/other means of collaboration on each computer.
• a running terminal (xterm/rxvt/Terminal/konsole/gnome-terminal etc etc) on each end.
• (optional, but a really good idea) a third computer (I'll call it bootes) to connect from, somewhere else outside of both percy and harry's networks. This is used to decide whose firewall to tweak.
• the hostname or externally-visible IP of all machines. This IP address varies between computers, but is generally the externally-visible address to connect to. If you have a hostname to connect to, so much the better, as then you can connect using that, though you still have to find out what that name is.
• install netcat on each machine, if it's not already installed. The method of install varies between package managers, ranging from "sudo apt-get install netcat" on an Ubuntu or Debian-based system to "urpmi netcat" on Mandriva. I'm not sure what it would be for Suse, Slackware or Mac OS X.

First test

• on the listening computer (harry), which we'll call the "host", start netcat in listen mode on a port, say 6900. Make sure that Cobalt is not running on either end when you do this, or else netcat will complain that it can't bind to the address, as only one application can use an address:port pair at any time
• on the sending computer (percy), which we'll call "client", type
• percy:bash$ nc -p 6900 harry.computer.ip.address 6900
• Type a line of text at the client end, and hit [Enter].
• percy:bash$ nc -p 6900 harry.computer.ip.address 6900

type in some text here<Enter>

• You should then see that same line of text pop out of the netcat at the host end.
• harry:bash$ nc -l 6900

type in some text here

• At the host end, type back a line, making sure you hit [Enter]. You should see that line turn up at the client end.
• harry:bash$ nc -l 6900

type in some text here

Here is some text in return<Enter>

• Once you see lines of text on both ends, the first test is concluded successfully.

Now, reverse the test machines, this time the host becomes the client, and the client becomes the host. You can hit <Control>C on each end to quit both netcat programs so you can start the test again.

Second test

• on the sending computer (harry), which we'll call "client", type
• harry:bash$ nc -p 6900 percy.computer.ip.address 6900<Enter>
• Then type a line of text (pretty much anything you like), and hit [Enter]. You'll see the cursor jump down to the next line.
• harry:bash$ nc -p 6900 percy.computer.ip.address 6900

type in some text here<Enter>

• You should then see that same line of text pop out of the netcat at the host end.
• percy:bash$ nc -l 6900

type in some text here

• At the host end, type back a line, making sure you hit [Enter]. You should see that line turn up at the client end.
• percy:bash$ nc -l 6900

type in some text here

Here is some text in return<Enter>

• Once you see lines of text on both ends, the second test is concluded successfully.

And that's roughly what we did. Now what to do if you don't see all/any lines of text.

First test results - needs fine tuning

If harry sees no lines of text, then percy probably won't see any reply lines either. It's actually pretty hard to judge whose firewall to look at unless you have multiple places you can connect from. If connections from anywhere fail to reach percy:6900, then check percy's firewall. If connections from harry don't reach percy, but connections from elsewhere (for example, from bootes) do, then check harry's firewall for outgoing connections to anywhere:6900 (or at least percy:6900). Connections are different to replies, as they're establishment of a link between two computers, whereas replies are continuances of an existing conversation between computers. For you techie types who've memorised the TCP stack, we're talking about the SYN portion of the setting up, not the SYN/ACK or ACK stages.

If harry sees lines, but percy doesn't see any lines in return, then harry needs to check outgoing reply traffic on port 6900, and percy needs to check incoming reply traffic on the same port. Again, this can be further refined if bootes can connect to percy:6900, in which case, check harry's firewall. If bootes cannot connect either, then check percy's firewall.

If both harry and percy see each other's lines, then we can establish that harry's firewall is probably set up correctly.

Second test results - needs rewrite

If percy sees no lines, then it's likely that harry's firewall isn't set up to allow outgoing connections on port 6900, or it's likely that percy's firewall isn't set up to allow incoming connections from anywhere:6900 (or at least, from harry:6900). This rather depends upon the results of the first test, because if that test failed, then both sets of firewalls need configuring. If the first test succeeds and the second test doesn't, then the setting up of each firewall differs from the previous case. In this case, harry needs to check their firewall for outgoing connections from harry:6900 to anywhere:6900.

If percy sees lines but harry doesn't see any lines in reply, then percy needs to check reply traffic from percy:6900 to anywhere:6900.

If both harry and percy see lines after both tests, then all firewalls are set up correctly for Open Cobalt connections. Congratulations.