BioMOBY Registry Scripts

The BioMOBY registry scripts are a required install for all you wishing to host your very own BioMOBY registry. These scripts contain the code that is used to retrieve information regarding the ontologies in RDF format, code for generating RDF that is served to the service providers upon successful service registration, an LSID resolution authority, and much more.

The following is a list of items contained in this release:

1. RESOURCES - a script that is used to generate RDF dumps for the Object, Namespace, Service Type, and Service Instance ontologies.
   
2. LSID Authority - a script that is used to resolve biomoby.org*, LSIDs to metadata.
   
3. Service Tester - a script that periodically 'pings' the services contained in the registry to determine whether or not the services URL are resolvable.
   
4. RDFAgent Validator - a form that can be used to test whether your installation of the agent was successful, or to test an RDF document that describes your services for syntactical errors.
   
5. Service Pinger Validator - a form that can be used to ping individual services so that you can determine whether there is a problem with that particular service.
   
6. Service Instance RDF Generator - a form that can be used to generate RDF for any pre-registered service, or a group of services, in the registry.
   

• Prerequisites
• Installation
• Configuration
  • Making RDF Downloads Faster
• Testing

Prerequisites

• These scripts may also require that a JAVA virtual machine version 5 or greater be installed on the machine hosting these scripts with the server environment appropriately set. JAVA_HOME should be set up both in your web server and in the servers environment. JAVA is required to run the RDFAgent.
• Finally, these scripts are meant to be used in conjunction with a BioMOBY registry and are not stand alone, so please ensure that you have installed your local registry first.

Installing the Scripts

Installing the scripts are extremely straight-forward and quite easy.

Installation Procedure

1. Please make sure to first update your moby-live checkout from the cvs. Further details can be found here.
   
   
2. Once you have an updated checkout of BioMOBY, cd into /moby-live/Perl/MOBY-Server/share/cgi/
   
   
3. Copy the following files to your webservers cgi-bin directory
   
   

             authority.pl
   
             ValidateService
   
             AgentRDFValidator
   
             ServicePingerValidator
   
             RESOURCES		  
   
             GenerateRDF.cgi 
   
             Moby        

   Copy the following file somewhere other than a web accessible directory (this script will be placed on a cron)
   
   

             service_tester.pl		  

   
   
   
4. You're done. All that is left for you to do is configure the newly installed scripts.

Please make sure that the first line of all the scripts corresponds to the correct location of your perl executable.
For instance if you perl is located in /bin/my/perl, then make sure to modify the first line of each of the scripts so that they read #!/bin/my/perl -w

Configuring Your Scripts

To Configure the servlets, you must know the following details regarding your local registry:

• The BioMOBY registry URL and URI
• The exact location of the mobycentral.config (confused? refer here)
• The exact location of the base directory for your JAVA installation

How to Configure

• Configure Your Environment
• Apaches httpd.conf
• mobycentral.config
• DNS records & Apache (If you wish to use the LSID authority script).
• Configuring the Service Tester script
• Configuring the RESOURCES script

Configure Your Environment

You will have to make sure that the following variables are set in the environment for the profile that your webserver will dispatch requests to. Most likely, they were set upon installation of the BIoMOBY registry.

• MOBY_CENTRAL_CONFIG=/path/to/mobycentral.config
• MOBY_URI=http://your.domain.here/MOBY/Central
• MOBY_SERVER=http://your.domain.here/cgi-bin/MOBY/MOBY-Central.pl

Optionaly, it wouldnt hurt to add one more:

• JAVA_HOME=/path/to/JAVA/DIR/

On *NIX machines, an example of how to set MOBY_SERVER is shown below:

set MOBY_SERVER=http://your.domain.here/cgi-bin/MOBY/MOBY-Central.pl

A better place for these variables would be in the profile of the user that starts the web server so that the variables can persist.

Configure Apache

You will have to make sure that the following variables are set in your conf (httpd.conf) file. In most cases, you will have done this already when the registry was installed.

In any case, the variables are listed below:

• SETENV MOBY_CENTRAL_CONFIG "/path/to/mobycentral.config"
• SETENV MOBY_URI "http://your.domain.here/MOBY/Central"
• SETENV MOBY_SERVER "http://your.domain.here/cgi-bin/MOBY/MOBY-Central.pl"

Optionaly, it wouldnt hurt to add one more:

• SETENV JAVA_HOME "/path/to/JAVA/DIR/"

Next, you will have to open the file mobycentral.config and add or modify a couple of configuration parameters:

• To the [mobycentral] section of this file, please ensure that the following parameters are set:

lsid_authority	Your domain name, as you would like it in urn:lsid:lsid_authority:namespace:object
lsid_namespace	The namespace that you would like service instances to use when resolving LSIDs, e.g. urn:lsid:lsid_authority:namespace:object
resourceURL	The URL that would return the RDF describing the service instances registered in your registry. This value is most likely: http://yourDomain:yourPort/authority/RESOURCES/MOBY-S/ServiceInstances
allResources	The URL that would return the RDF describing all ontologies in your registry. This value is most likely: http://yourDomain:yourPort/authority/RESOURCES/MOBY-S/FULL
service_tester_path	The full readable/writeable path that the service tester can place persistent data between invocations . This can be any directory, including a temporary one. Make sure that the scripts invoked through apache and from the command line can read/write to it. Note: the service tester does not currently work on windows!
rdf_cache	The full readable/writable path that the RESOURCES script can place cached RDF related files. This can be any directory, including a temporary one. Make sure that the scripts invoked through apache and from the command line can read/write to it.

 

• To the [mobyobject] section of this file, please ensure that the following parameters are set:

lsid_authority	Your domain name, as you would like it in urn:lsid:lsid_authority:namespace:object
lsid_namespace	The namespace that you would like Objects to use when resolving LSIDs, e.g. urn:lsid:lsid_authority:namespace:object
resourceURL	The URL that would return the RDF describing the datatypes registered in your registry. This value is most likely: http://yourDomain:yourPort/authority/RESOURCES/MOBY-S/Objects

 

• To the [mobynamespace] section of this file, please ensure that the following parameters are set:

lsid_authority	Your domain name, as you would like it in urn:lsid:lsid_authority:namespace:object
lsid_namespace	The namespace that you would like namespaces to use when resolving LSIDs, e.g. urn:lsid:lsid_authority:namespace:object
resourceURL	The URL that would return the RDF describing the namespaces registered in your registry. This value is most likely: http://yourDomain:yourPort/authority/RESOURCES/MOBY-S/Namespaces

 

• To the [mobyservice] section of this file, please ensure that the following parameters are set:

lsid_authority	Your domain name, as you would like it in urn:lsid:lsid_authority:namespace:object
lsid_namespace	The namespace that you would like service instances to use when resolving LSIDs, e.g. urn:lsid:lsid_authority:namespace:object
resourceURL	The URL that would return the RDF describing the service types registered in your registry. This value is most likely: http://yourDomain:yourPort/authority/RESOURCES/MOBY-S/ServiceTypes

 

To enable the LSID authority script, you will have to perform up to 2 more tasks:

• Create a DNS record for your domain
• Add a ScriptAlias directive

Setting up DNS (excerpt)

All that you - or your system administrator - must do, is to add a service record for the machine that will run the authority.

Suppose the machine is authority.company.net and that it will serve as the authority named company.net. Further suppose that the service will be on port 8080. The record that must be added should go into the master zone file for company.net's DNS server (perhaps a file named /var/named/company.net.zone on company.net):

_lsid._tcp      IN      SRV     1       0       8080    authority.company.net.

If the authority name is supposed to be authority.company.net rather than company.net, the record in company.net's zone file should look like:

_lsid._tcp.authority    IN      SRV     1       0       8080    authority.company.net.
      

Adding a ScriptAlias Directive

All that you - or your system administrator - must do, is add the following directive to your web server configuration file:

ScriptAlias /authority "/path/to/apache/cgi-bin/authority.pl"
      

 

Once these values have been added or modified, make sure to save the configuration files and restart the server. Your changes should be reflected in your registry.

Configuring the Service Tester

To set up the service tester (service_tester.pl), you will have to do 2 things.

1. Add the script to a cron job to execute at time intervals >= 1 hour.
   

Note: When setting up the cron job, make sure that MOBY_CENTRAL_CONFIG is visible in the cron's environment. One way of doing this is to do something like the following:


     * * * * * /bin/su - root -c /path/to/your/service_tester.pl

Of course, you will need to modify the timing of the job, i.e. the * * * * * bit!

1. Modify script specific variables (although, the default values should be fine)

The user configurable variables for the service tester are listed below with their descriptions. To modify them, open up the file service_tester.pl and change the values to those values you wish to have.

• TIMEOUT - this is the amount of time the script is willing to wait before it assumes that the service being tested has timed out. By default, this 50 seconds.
• THREAD_COUNT - the maximum number of threads that you would like testing services at any given time. By default, this is 15.
• CATEGORIES - the service categories that you would like to test. By default, 'moby' is the only service category tested.
• URL - the BioMOBY registry endpoint that we will poll for services to test. This value is usually obtained from the environment and shouldn't be modified.
• URI - the BioMOBY registry namespace that we will poll for services to test. This value is usually obtained from the environment and shouldn't be modified.

 

Configuring the RESOURCES script

To set up the RESOURCES script, you may have to do 2 things.

1. If you plan to set up file caching, then you will have to create a directory with the appropriate permissions for the script to read/write.
2. Modify script specific variables (although, the default values should be fine)

The user configurable variables for the service tester are listed below with their descriptions. To modify them, open up the file service_tester.pl and change the values to those values you wish to have.

• useCache- Caching is enabled by default and can be toggled by modifying
  $useCache [0 => disabled, 1 => enabled].
  Caching really speeds up the generation of RDF and is highly recommended.
• dir - dir is the cache directory that the script will output cached files into and read from. By default, '/tmp/' is the directory. Please ensure that the web server can read/write into this directory.

Making RDF Downloads Faster

To speed up downloads of the RDF fles that the RESOURCE script serves, you will need to enable mod_deflate on your Apache webserver.

Of course, the details on how to do this on your system may differ, but in general, the steps involved are:

1. Open your httpd.conf file and add the following line:
   




LoadModule deflate_module path/to/modules/mod_deflate.so

Of course, you will have to update the path/to/modules to reflect where it is that you have mod_deflate.so installed.

2. Append following configuration <Location /> directive:




<Location />

   # compress only the following mime types               
   AddOutputFilterByType DEFLATE text/html text/plain text/xml application/xml application/rdf+xml

   # Make sure proxies don't deliver the wrong content
   Header append Vary User-Agent env=!dont-vary

</Location>

Feel free to add more mime types.

3. Last, but not least, restart your web server.
   

Testing Your Scripts

Once you have installed and configured the scripts, you can determine if the install was successful by attempting to resolve the following URL:

http://your.domain.com:your_port/cgi-bin/Moby

where your.domain.com is the domain name of the server that the servlets were installed on and your_port is the server port.

The resulting page will outline those scripts that are included in this distribution and will provide you with links to test them.