Installation Guide - Grimoires

Grimoires directory structure

After you download and unzip Grimoires, you will see the following directory structure inside.

  • src/: source code
    • grimoires.properties: set up runtime options, e.g., which RDF triple store to use.
  • lib/: where Grimoires server jar is generated, and all third party jars required by Grimoires
  • docs/: documentation
    • api/: javadoc
  • wsdl/: wsdl files and xsd schemas for all Grimoires services
  • config/: configuration files for various containers
    • axis/: configuration files for standard Apache Tomcat
    • gt4/: configuration files for GT4 container
    • omii/: configuration files for OMII without signed SOAP message support
    • omii-sec/: configuration files for OMII with signed SOAP message support
  • dist/: where binary release files (war file or gar file) for various containers are generated
    • client/: Grimoires client
    • server/: Grimoires server
  • wstester/: junit test suite
  • GShell/: Grimoires shell, Grimoires' command line client tool
  • licenses/: third party licenses
  • init.properties: set up the compilation and deployment options for Grimoires. Users need to edit this before compilation and deployment.
  • build.xml: Ant build file containing all ant targets to compile and deploy Grimoires. Users do not need to edit this file to compile and deploy Grimoires.
  • LICENCE: the licence statement.
  • README: a read me file.

Configuration

There are two main configuration files in Grimories: init.properties contains the compilation and deployment options, and grimoires.properties contains Grimoires' runtime options. There are also several options that may need to be set for a secure deployment of Grimoires.

Compilation and deployment: init.properties

All the configurable parameters required to compile and deploy Grimoires can be located in init.properties.

  • [Required] Target container: omii-sec, omii, axis, or gt4. For instance, 
container = omii

As mentioned in the getting started guide , Grimoires has three target containers, OMII, Tomcat and GT4. The corresponding options for this parameter are i) omii - the supported version of the OMII container; ii) omii-sec - the supported version of the secure OMII container. This requires that request messages to Grimoires must be signed in accordance with X509 standards, and the Distinguished Name (DN) of the accompanying certificate be extracted; (refer to the security  guide for further information) iii) axis - the supported versions of Tomcat and Axis; iv) gt4 - the supported version of the Globus Toolkit 4 container.

  • OMII specific options, which are REQUIRED if either the option "container = omii" or "container = omii-sec" is chosen. For instance, 
securitytype = basic

This parameter is only relevant if a secure OMII container deployment is chosen (i.e. option "container = omii-sec"). It determines the type of access control to be enforced on incoming requests to Grimoires. There are currently two options: i) basic - this is very basic access control. As long as the incoming request message has an accompanying signature that is verifiable to the OMII server (i.e. whose public key certificate was signed by the OMII CA), it is permitted through. ii) acl - the DN from the certificate is used in an XML based access control list to ascertain whether the request is permitted or denied. Refer to the security guide for further information. 

tomcat.host = http://gallagher
tomcat:port = 18080
omii.context.path = grimoires
omii.tomcat.username = tomcat
omii.tomcat.password = tomcat

In the above case, Grimoires will be deployed in http://gallagher:18080/grimoires. The username of a valid tomcat account of a manager role is "tomcat", and the corresponding password is "tomcat".

  • Axis specific options, which are REQUIRED if the option "container = axis" is chosen. For instance, 
axis.tomcat.url = http://localhost:8080/
axis.context.path = grimoires
axis.tomcat.username = tomcat
axis.tomcat.password = tomcat

In the above case, Grimoires will be deployed in http://localhost:8080/grimoires. The username of a valid tomcat account of a manager role is "tomcat", and the corresponding password is "tomcat".

  • GT4 specific options, which are REQUIRED if the option "container = gt4" is chosen. For instance, 
gt4.url = http://localhost:8080
gt4.home = /home/gt395/gt4

Run time options: grimoires.properties

Currently, grimoires.properties controls the RDF triple store configuration in Grimoires as well as some relevant security parameters. The grimoires.properties file can be found in the distribution in src/. After Grimoires is deployed, grimoires.properties appears in webapps/grimoires/WEB-INF/classes, assuming axis.context.path = grimoires. All the options controlling Grimoires' runtime behavior appear here. If the "securitytype = acl" option is chosen for a deployment of a secure OMII container, the location of the access control list to be used by Grimoires is specified here. The default value is correct with respect to the default deployment of Grimoires into the secure OMII container. 

# Location of authorization file for a secure deployment of Grimoires in OMII using an XML ACL
# This sets the location of the file containing the list of X509DNs and the operations permitted to them
# by default, this is set to the authlist.xml file located at the WEB-INF directory of the WAR (or Axis) deployment of Grimoires.

authfile = /usr/local/OMII/jakarta-tomcat-5.0.25/webapps/grimoires/WEB-INF/authlist.xml

There are various triple stores supported by Grimoires. We use the "store" property to denote different triple store configurations. E.g., "sesame" represents a Sesame repository, which includes (file-backed) in-memory, native, rdbms-based Sesame repository. "memory" represents a Jena in-memory store. "file" represents a Jena file-backed in-memory store. "bdb" represents a Jena Berkeley DB based store. "mysql" represents a Jena MySQL-based store. "postgresql" represents a Jena PostgreSQL-based store.

To configure, choose any of these store types, as well as its associated properties, and comment out all other properties. To configure the Sesame store, choose any of the Sesame repositories, as well as its associated properties, and comment out all other properties.

Below are grimoires.properties samples for each available triple store configuration.

Sesame in-memory triple store
# Various Sesame repositories
store = sesame
# Sesame in-memory repository
sesame.repository = memory
# Is reasoning required?
sesame.inferencing = false
# If multiple users access the triple store simultaneously, should they be synchronized? This is set to false because Grimoires has its own synchronization layer.
sesame.sync = false
# The backup file. Make sure Grimoires has the permission to access this file.
# sesame.file = sesame.rdf
# The representation format of RDF statements. "ntriples" is most efficient.
# sesame.format = ntriples
# The time delay from a publication to its corresponding dump to the file. If there is another publication before the timer expires, the timer is reset.
# sesame.syncDelay = 60000
Sesame rdbms-based triple store
# Various Sesame repositories
store = sesame
# Sesame rdbms-based repository
sesame.repository = rdbms
sesame.sync = false
# Database drive
sesame.jdbcDriver = org.postgresql.Driver
# JDBC URL
sesame.jdbcUrl = jdbc:postgresql://localhost/sesame
# Database username
sesame.user = sesame
# Database password
sesame.password = sesame
Sesame native triple store
# Various Sesame repositories
store = sesame
# Sesame native repository
sesame.repository = native
sesame.sync = false
# A directory where RDF triples are dumped. Make sure Grimoires has the proper permission to access it.
Sesame.dir =  c:\\sesame
Jena in-memory triple store
# An Jena in-memory backend
store = memory
Jena file-backed in-memory triple store
# Memory model backed by files
###################
store = file
# A directory where RDF triples are dumped. Make sure Grimoires has the proper permission to access it.
root = L:\\Documents and Settings\\wf\\My Documents\\workspace\\Grimoires\\store\\
Jena Berkeley DB based triple store
# Berkeley DB store
###################
store = bdb
# A directory where RDF triples are dumped. Make sure Grimoires has the proper permission to access it.
dbfile = c:\\BDBStore
# DB name
dbname = Grimoires
Jena MySQL-based triple store
# MySQL
###################
store = mysql
# JDBC URL
url = jdbc:mysql://localhost:3306/grimoires
# DB username
user = grimoires
# DB password
password = grimoires
Jena PostgreSQL-based triple store

# PostgreSQL
###################
store = postgresql
# JDBC URL
url = jdbc:postgresql://localhost/Grimoires_Benchmark
# DB username
user = grimoires
# DB password
password = grimoires

Security options

If Grimoires is to be deployed in a secure mode (i.e. with "container = omii-sec"), some configuration parameters need to be set in order to ensure that the appropriate keystore is being accessed. The file crypto.properties in /config/omii-sec/classes/conf is as follows: 
org.apache.ws.security.crypto.merlin.file=/usr/local/OMII/omii.ks
org.apache.ws.security.crypto.merlin.keystore.password=tmpstore
org.apache.ws.security.crypto.merlin.keystore.alias=omii_server
org.apache.ws.security.crypto.merlin.alias.password=tmpstore
org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=JKS
org.apache.ws.security.crypto.merlin.crldir=/usr/local/OMII/grid/CRLs
The org.apache.ws.security.crypto.merlin.file parameter should be reflect the correct location of the OMII container root directory. By default, this is /usr/local/OMII; if an installation is made to a different directory, then this parameter must be changed accordingly. In addition, the access control list file should be set accordingly prior to deployment, if access control is desired.

Deployment

build.xml

Having set up the options in init.properties to the proper values in your environment, you can call the ant targets in build.xml to compile and deploy Grimoires to your selected container. Here we list all the ant targets for public use:

  • clean: clean up all the compiled classes and generated jars. This should be called if you choose another container in init.properties. For instance, if you set "container = omii" then modify it to "container = axis", you need to call "clean" before you compile Grimoires.
  • release: print the version information of Grimoires.
  • build-all: build java doc, generate the war file or gar file (for GT4) which is deployable, based on the options set up in init.properties, and build the client.
  • deploy: deploy Grimories (war file or gar file) to the container, based on the options set up in init.properties. "deploy" will call "make-dist". The Grimoires services should be located at:
    • UDDI Publish URL: http://hostname:18080/grimoires/services/publish
    • UDDI Inquire URL: http://hostname:18080/grimoires/services/inquire
    • WSDL interface URL: http://hostname:18080/grimoires/services/wsdl
    • Metadata Publish URL: http://hostname:18080/grimoires/services/publish_metadata
    • Metadata Inquire URL: http://hostname:18080/grimoires/services/inquire_metadata
    • WSDL Metadata Inquire URL: http://hostname:18080/grimoires/services/inquire_wsdlMetadata
    • UDDI Metadata Inquire URL: http://hostname:18080/grimoires/services/inquire_uddiMetadata

  • undeploy: undeploy Grimoires from the container, based on the options set up in init.properties.
  • test-install: Test whether Grimoires is deployed in a container properly. It will access each deployed Grimoires service using http protocol, and print the information it get. For instance, it will get http://localhost:18080/grimoires/services/publish. If the publish servie is successfully deployed, you will see 
<h1>publish</h1>
<p>Hi there, this is an AXIS service!</p>
<i>Perhaps there will be a form for invoking the service here...</i>
  • test-junit: Use the junit test suite to test against deployed Grimoires. Before run this target, you need to set up wstester/bos.properties. For instance, if Grimoires is deployed on the http://localhost:18080/grimoires/, registryBaseURL = http://localhost:18080/grimoires/services.

IMPORTANT - the test-install and test-unit targets are only designed to run successfully against Grimoires in a standard (i.e. non-secure) OMII container.