Everything Else
TS484: Configuring Helix 5.0–5.2.1 for Access through a Firewall

This configuration note applies to Helix 5.0–5.2.1 only. The information below does not apply to Helix 5.3 or later.


Configuration Note


A Helix Client (5.0-5.2) can't reliably connect to a Helix Server that is behind a firewall.


A firewall, which segments a network into two physical sub networks, restricts unauthorized access to internal networks. A firewall acts as the gateway between the two networks; one side of the firewall connects to a public network (e.g. the Internet) and the other connects to a private network. When a request is made for data to pass through the firewall, the data is "filtered" and if the necessary criteria are met, traffic is allowed. The absence of those criteria causes the firewall to block the communication. When data is allowed to pass through the firewall, a port is opened between the two networks and the data passes through.

In order for a Helix Client to access a collection hosted by a Helix Server that is protected by a firewall, the network manager must configure the firewall to allow the required traffic. Communication between Helix Server and Client is as follows. By default, Helix Server listens for incoming requests on TCP port number 10850. (This port number is stored in a resource in the Helix applications that can be changed using a resource editor.) When a request is made (on port 10850) the Helix Server will reply via one or more streams of data, each requiring its own port. These port numbers are randomly assigned, but are all initiated by Helix Server.


Given the default configuration, the firewall must be configured as follows...

  1. The firewall must be set to accept unsolicited connections to Helix Server via port 10850.
  2. The firewall must be set to accept all inbound traffic that the server initiated (ACK set).

These two settings will allow a Helix Client to access a Helix Server that is on a network protected by a firewall.

Additional Notes

When the Helix Client initiates communication to the Helix Server, the client uses port 10850; when the Helix Server initiates communication to the client, the server uses dynamic port numbers for both sending to and receiving responses from the client. These dynamic port numbers are usually (but not necessarily) greater than 1023. Therefore, if the Helix Client is behind a firewall, attempts by the Server to contact the Client will be turned away by the firewall if the port is not set to allow unsolicited connections. Since port assignment in this direction is random, we can not predict which port requests will come in on, and unless all ports are open (which would be the effective equivalent of turning the firewall off) there is a chance that the data will be rejected. If this happens, Helix Server will assume (after a timeout period) that the Client has crashed and terminate the connection completely. Therefore you can see that passing Helix via TCP/IP will only work properly if Helix Client is not behind a firewall. We acknowledge that this is a serious limitation and plan to address it in a future release.

Helix Client and macOS Personal Firewall

OK, now that we've said you can't use a Helix Client that is behind a firewall, we'll turn around and say you really can. The problem from a traditional firewall standpoint is that you never know which ports a particular Helix Client will attempt to use. However, with the introduction of the personal firewall in macOS 10.2, it is possible for a Mac running Helix Client to be responsible for its own firewall, making it much more convenient to 'punch a hole' in the firewall for Helix TCP/IP traffic.

How can I be sure this is my problem?

The typical symptom of a Client behind a firewall is that the Client is able to successfully connect to the Server, but opening a list results in Helix's "spinning arrow" cursor. You should also see that popup menus on entry forms never fill in, remaining greyed out indefinitely. Lists and popup menus are asynchronous processes, and Helix TCP/IP uses one of its additional ports for each such process. So, if your lists and popup menus don't work, yo can safely conclude that your Client is behind a firewall.

The Basics
  1. Port 10850 must always be open and available.
  2. When a Client is launched, it establishes another random port (known as the 'base port') and then open 32 consecutive ports, counting up from the base port that was chosen.
  3. Accoring to the original Helix TCP/IP programmer (who left long ago, but didn't leave any documentation on his work) Helix Client can use up to 100 distinct ports. That number seems odd to us, but you should play it safe and open up a range of 100 ports in your firewall.
  4. Keep in mind that every time a Helix Client is Quit and relaunched, it will choose a new base port, so your old settings will almost certainly not work.
Configuring macOS Firewall

The simplest solution is to temporarily turn off the firewall in the Sharing preference pane. To keep the macOS Firewall active, follow these steps to add the necessary ports:

  1. Launch Helix Client
  2. Wait until the wristwatch cursor turn back into an arrow
  3. Choose Apple menu > About Helix Client. The Helix Client splash screen opens
  4. In the Host line, note the 4 or 5 digit number that comes after the colon. (If it is 0, click on the splash screen to close it, then repeat the previous step.
  5. Write down that number, and label it 'xxxxx'
  6. Add 100 to that number, write this number down, and label it 'yyyyy'
  7. Click on the splash screen to dismiss it
  8. Click on the desktop to switch back into the macOS environment
  9. Choose Apple menu > System Preferences
  10. Choose View > Sharing
  11. Click the Firewall tab
  12. Click New
  13. Choose Other from the Port Name pop-up menu
  14. In the Port Number, Range or Series field, type in: 10850, xxxxx-yyyyy, where xxxxx & yyyyy are the two numbers you wrote down before
  15. In the Description field type in: Helix Client, 1 Time
  16. Click OK

You should now be able to connect to a Helix Server without difficulty. If it does not seem to be working, recheck the Host info and the information you entered into the Firewall tab.

Final notes: You can change the firewall settings 'on the fly' while connected to a Helix Server. Changes take effect immediately when you click OK.

You don't have to create a new port mapping entry each time you use Helix Client. Just update the port range with the new xxxxx & yyyyy values.

If it doesn't seem to be working, try temporarily turning the firewall off altogether. If Helix Client still doesn't work, there is something else blocking your access.