Galaxy Communicator Documentation:

Coordinating Locations of Hub and Server Listeners


By default, servers start up listeners on their default ports, and the Hub contacts them. Alternatively, you can set up a listener in the Hub and have the server contact the Hub instead. In both these cases, the programmer needs to make sure that the server entries in the Hub program file, the default server header, and the server command line arguments all correspond to each other, so that the Hub and servers can connect. Not only can this be a difficult and unreliable procedure, but it's also possible that multiple instances of the same Communicator system might be running at the same site on different sets of machines. In this latter case, the scripts and program files for the system would typically have to be modified for each invocation (or separate versions would need to be maintained). The overhead of this chore can be extremely frustrating.

In version 3.0, we've implemented a simple solution to address this issue.


The server locations file

In version 3.0, both the Hub and servers accept a command line argument -server_locations_file which names a file which describes where the listeners are located. The format of each meaningful line of this file whould be as follows:

<server_name> <listener_host_or_ip>:<listener_port> [hub|server]

On the Hub side, <server_name> is the name of a service type; on the server side, it's the name the server knows itself as. When the Hub is the listener, the Hub uses the port as the listen port for the named service type; when it's the client, it uses the host and port as the location of a service provider for the named service type. So it's important for the Hub and server to know the server by the same name. The <listener_host_or_ip>:<listener_port> is the location of the listener for this connection, and the third element is either hub or server depending on whether the listener is in the Hub or the server.

For example, the following server locations file describes a situation where the Hub has a listener on port 3600 listening for connections from a server named multiply, and a server named double opens up its own listener on port 5200. In addition, the multiply server will try to find that Hub listener on bolcom.mitre.org (so the Hub had better be running on that machine), and the Hub will try to find the double listener on feta.mitre.org (so the double server had better be running on that machine):

multiply bolcom.mitre.org:3600 hub
double   feta.mitre.org:5200   server

So as long as the Hub starts up on bolcom.mitre.org and is passed this server locations file, and as long as the double server starts up on feta.mitre.org and is passed this server locations file, and as long as the multiply server starts up somewhere and is passed this server locations file, this system configuration will initialize itself appropriately:

bolcom.mitre.org$ hub -server_locations_file double.loc
---------------------------------------------------------
feta.mitre.org$ double -server_locations_file double.loc
----------------------------------------------------------
somewhere.mitre.org$ multiply -server_locations_file double.loc

The result is that it's possible to configure a suite of servers and Hub with a single configuration file, and no scripts or program files need to be changed.

Note: this utility does not currently provide a facility for ensuring that the listener is started on the correct host. The crudest version of this support would be to shut down if the specified host wasn't the host the listener was running on, but it's not clear whether this would work for DHCP connections, for instance.

Locations file syntax

In addition to the meaningful lines described above, all lines consisting entirely of whitespace are ignored, as are all lines whose first non-whitespace character is #. There can be any nonempty amount of whitespace in between the three tokens in each meaningful line.

Server locations files and other command line arguments

The server locations files override all other port information. On the Hub side, it supersedes the host and port information in the program file and in the -locations command line argument. On the server side, it supersedes the information in the server declaration header file, as well as the -port and -contact_hub command line arguments. On both the Hub and server sides, the specified port for the listener is required; the listener startup process will not search for the first available port, but rather fail if the specified port is not available.

Note: this override mechanism only works in the Hub when there is at most one service provider for the named service type.


Please send comments and suggestions to:bugs-darpacomm@linus.mitre.org
Last updated December 6, 2000.

Copyright (c) 1998, 1999, 2000
The MITRE Corporation
ALL RIGHTS RESERVED