This is the README for $CIPRES_ROOT/share/cipres/resources/ports
================================================================================

========
Overview
========
Each user runs their own CIPRES property service and CIPRES registry. Usually
these processes should be run as daemons.

The IORs for each user's services are stored in files in this ports directory.
When a CIPRES client process asks for a reference to one of these services,
library code finds the appropriate IOR file and tries to connect to the service.
The library code will launch a new instances of these services if the files do
not exist (or the IORs in the files are invalid or refer to objects that are
responsive).


=======
Details
=======
The user's property service IOR is stored in a file named:
	<user>_property.txt
The user's registry IOR is stored in:
	<user>_registry.txt

When CIPRES is installed on a network where the nodes share a filesystem, and 
this ports directory is on the shared filesystem this simple naming system will
not work. Different machines would end up sharing registries making it
impossible to control where jobs were run).  There must be one of each service 
running on each host for each user. In the context of a shared fs the IOR files 
include the hostname in them:

	<user>_<hostname>_property.txt.
	<user>_<hostname>_registry.txt

Note that on some OS (e.g. Mac), the hostname of machines with wireless internet
connection change with the wireless network.  Thus we do not use the hostname
in the IOR file name by default. Thus, our solution assumes that CIPRES will not
be installed on a shared fs that has unstable hostnames.

Only the services themselves need to pay attention to whether or not the 
installation is using the shared fs naming convention.  Library code for use
by clients can simply check for the <user>_<hostname>_*.txt form first and, if the
file is not found, check for <user>_*.txt

	If you've installed cipres on a cluster with a shared filesystem you can tell
	the property service to include the hostname in the filename either by setting
	the environment variable CIPRES_SHAREDFS=1, or by launching the property service
	with the system property cipres.sharedFS=1 or by creating a file named
	cipres.sharedFS in the "resources" directory of the cipres installation.  If any of
	these are set, the property service includes the hostname in the filename, and 
	makes the property "cipres.sharedFS=1" available to any other service (such
	as the registry) that need to know whether to use the hostname in their port
	filename.

The files in the ports directory contain the service's ior on the first line, and the
process ID of the service on the second line.

The property service is always started on the local loopback address, 127.0.0.1.  The
registry however, listens for connections on a network interface so that it can be included in a 
federation of remote registries.  In the future we may put two iors in the registry's file; the first
would be a local loopback address, the second would be an externally accessible ior.  The reason we
don't want to use just the externally accessible ior, is for the case where a user is running services
locally on his laptop and moves off a the network.  In that case, he can continue to contact a 
running registry on the loopback address.


==================
Launching services
==================
If these files IOR files do not exist then, one can assume that the user is 
not running the required CIPRES services.  Normally the libraries will launch 
the services as needed (and leave them running).  But the services can be 
manually started using the script $CIPRES_ROOT/bin/cipresctl

This script takes a command start|stop|restart|status