Installation LS snapshot 2006-09-19

From GEANT2-JRA1 Wiki

[edit]

Short

[edit]

Requirements

  • Tomcat, Axis, Java and Ant installed
[edit]

Procedure

  • download and unpack snapshot tarball
  • enter ant directory 
 cd perfsonar/ant
  • download JAR files 
 ant libs-xmlls
  • configure LS 
 ant configure-xmlls
  • compile LS 
 ant build-xmlls
  • LS is ready to be deployed (start Tomcat) 
 ant undeploy-xmlls         #if necessary
 ant deploy-xmlls
  • LS is ready to be tested: 
 ant ls-run-client-register
 ant ls-run-client-query
 ant ls-run-client-deregister

Contents


[edit]

Detailed description


This document contains some hints how to install and configure Lookup Service and then test its functionality. This installation guide may be applied either to a single instance of the service running on the server or to more than one instance of a service runnig on the same server (e.g. LS and MA). Additional information how to configure Tomcat and Lookup Service to run as additional service are provided when necessary.

[edit]

Installation

[edit]

Pre-requisities

Use these instructions to download and install additional software

[edit]

Step 1 - Java Development Kit (JDK) 2 Platform

For a successful install we recommend JDK version 1.5, which has been tested. Current code will not compile on version 1.4. Download and extract Java 2 Platform Standard Edition from http://java.sun.com/j2se/1.5.0/download.jsp.

[edit]

Step 2 - Apache Ant

Apache Ant is a Java-based build tool compulsory to proceed with other steps that are using Ant scripts. Download Ant from http://ant.apache.org/bindownload.cgi and install it.

[edit]

Step 3 - eXist XML database

[edit]
Step 3.1 - Getting sources

xXist database needs to be installed. Download eXist from http://exist-db.org/index.html#download]. It is suggested that you use Development snapshot. Lookup Service was tested with eXist-snapshot-20060316.jar version of database, so I suggest tu use this version.

[edit]
Step 3.2 - Installing eXist

To run graphical installer of eXist enter the following command and select the path for installation when asked: 

 java -jar eXist-snapshot-20060316.jar

To run command line installation of eXist enter the following command and specify installation path as a parameter (you should replace $EXIST_HOME with your own selected path): 

java -jar eXist-snapshot-20060316.jar -p $EXIST_HOME

The rest of this document assumes that eXist directory name is under $EXIST_HOME e.g /usr/local/exist.


[edit]

Acquiring service code

[edit]

Step 4 - Getting service sources

Before installing the service, you should decide which method of getting sources you would like to use. You can get service sources from #SVN or download a #Snapshot tar file which only contains the required sets of packages:

[edit]
SVN

The latest version of is available from perfSONAR SVN. See SVN usage details page.

[edit]
Snapshot

The latest snapshot is available on perfSONAR Wiki.

You can download Lookup Service code to any directory in your server. By default, tar will create files into ./perfsonar. The rest of this document assumes that the Lookup Service full directory name is under $PERFSONAR_LS e.g./usr/local/jra1-project/ls.

Into selected directory download Lookup Service snapshot tar file from download page

While using snapshot you also need Tomcat and Axis downloaded separately. To download and install them use Apache homepage or run the following command in $PERFSONAR_LS/ant directory: 

ant webservice-container-download

If you have another service (e.g. MA) running on the same machine you will have to run another instance of Tomcat using another port. Follow appropriate instructions.

[edit]

eXist startup

eXist uses a Jetty server. It is also possible to run it from Tomcat, but it's a little bit harder (you'll need to deploy eXist and COCOON manually). If you decide to use Jetty, remember that it mustn't use the same port as Tomcat, where the Lookup Service resides.

[edit]

Step 5 - Changing default port

To change the eXist default server port, open $EXIST_HOME/bin/startup.sh file and find OPTIONS line which should look like: 

 OPTIONS="-Dexist.home=$EXIST_HOME"

Then alter that line adding new port number at the end: 

 OPTIONS="-Dexist.home=$EXIST_HOME -Djetty.port=8680"

8680 is an example of new port number (default is 8080). This 8680 port number will be used in next examples. You must change it into your own one where necessary.

[edit]

Step 6 - Running an eXist server

After the installation and configuration has completed, you should be ready to launch eXist. To run eXist server enter the following commands: 

cd $EXIST_HOME/bin
./startup.sh

It starts the included Jetty webserver at previously configured port i.e. eXist and Cocoon are installed as a web application, located at http://localhost:8680/exist/

[edit]

Step 7 - Running the eXist client tool

eXist client can be launched in two ways: first, you may use eXist's GUI, second, you may use the shell mode. Without an action, the client switches to interactive mode and displays the graphical user interface. It is also possible that the client switches to shell-mode and prompts for user input.

[edit]
GUI

Simply run client script without any parameters: 

 cd $EXIST_HOME/bin
 ./client.sh

and enter URL in database login window pointing to your eXist location e.g. xmldb:exist://localhost:8680/exist/xmlrpc Then connect to the server.

[edit]
Shell mode

The shell-mode is invoked using the following command (it provides access to a server running inside the Jetty webserver at port 8680 on a local host): 

cd /$EXIST_HOME/bin
./client.sh -s -ouri=xmldb:exist://localhost:8680/exist/xmlrpc

When connected successfully you should see eXist database prompt: 

exist:/db>

You will find more information about eXist integrated command-line client pointing towards eXist home page.

[edit]

Step 8 - Importing data with database client

The following examples will guide you through shell-mode of eXist client. If you use GUI you will find all relevant comands in menus. For more information refer to eXist quick start pages.

  • First create user account for Lookup Service entering the following commands in eXist shell: 
exist:/db>adduser lookupservice
password: sonar
re-enter password: sonar
home collection [none]: 
enter groups: guest
user <...> created

These are just examples and you can use other login/password of your own choice.

  • Create collection "ls" (or other for Lookup Service storage) 
exist:/db>mkcol ls
created collection.
  • Create two XML files in the ls collection by importing data from example XML files: 
exist:/db>cd ls
exist:/db/ls>put $PERFSONAR_LS/schema/example-instances/sonar/LS/test/LSStore.xml
exist:/bd/ls>put $PERFSONAR_LS/schema/example-instances/sonar/LS/test/LSStore-control.xml
  • Set user/group rights if necessary. Use: 
exist:/db/ls>chown lookupservice guest LSStore.xml
exist:/db/ls>chown lookupservice guest LSStore-control.xml
  • Change rights to access these resources if necessary. User lookupservice:guest should have R/W access to both resources.
  • IShould any problem happen with access control it is suggested to use eXist client GUI instead of shell-mode, because commands mkcol and chmod may not work in some versions of eXist DB.


[edit]

Configuring service properties

Compilation and deployment process may be done by ANT scripts. You should use build-xmlls.xml ANT script file. All "ant" commands below contain -f build-xmlls.xml, but you may omit this by:

  • copying build-xmlls.xml as default build.xml 
cd $PERFSONAR/ant
cp build-xmlls.xml build.xml
  • create symbolic link: 
cd $PERFSONAR/ant
ln -s build-xmlls.xml build.xml

Then you will be able to use just ant TARGET instead of ant -f build-xmlls.xml TARGET

[edit]

Configuration

[edit]

Step 9 - Download JAR libraries

All required perfSONAR Lookup Service libraries (JAR files) are in jar-repository. 

ant -f build-xmlls.xml libs-xmlls

Some of libraries will be downloaded from remote (public) repository and some from local (perfSONAR) one. So don't care about download warnings...

[edit]

Step 10 - Preparing configuration files

Here we are going to set up some properties necessary to run the service. It's better that you call Ant script which will interact with you to do it automaticaly. To generate config files and setup properties run the following command: 

cd $PERFSONAR_LS/ant
ant -f build-xmlls.xml configure-xmlls

When asked for the base path for the application provide $PERFSONAR_LS path where conf and ant are. Base path will be used for copying template files. Then you will be asked questions where you may accept default avlues. When finished you'll have the following files copied from conf/template directory:

  • ant/const.properties
  • conf/service.properties
  • conf/components.properties
  • conf/log4j.properties

You can always edit above files manually to change settings or modify supported functionality. But remember, all these files are required for running the Lookup Service.

[edit]

Step 11 - Example questions: 

    [echo] ---------------------------------------------------------------
    [echo] Enter your settings. Set at least [base path] and [host name],
    [echo]   other may remain default (default values may be accepted just
    [echo]   by pressing ENTER)
    [echo] ---------------------------------------------------------------
   [input] Enter base path for the application [/projects/sonar/1/perfsonar]
  • base path will be determined automaticaly on linux/unix OSes, but you may change it 
   [input] Enter hostname [your.host.com]
  • it should be your full host.domain, such as alfa.domain.com 
   [input] Enter service name [Lookup Service]
  • enter name 
   [input] Enter log configuration file [/projects/sonar/1/perfsonar/conf/log4j.properties]
  • you may just accept default settings in most of cases 
   [input] Enter logs directory [/projects/sonar/1/perfsonar/log]
   [input] Enter path for parser configuration file [/projects/sonar/1/perfsonar/src/objects.config]
   [input] Lookup Information of service -- access point (URL) [1]
   [input] Lookup Information of service -- service name [Test Lookup Service]
   [input] Lookup Information of service -- service type [LS]
   [input] Lookup Information of service -- service description [Test Lookup Service, perfSONAR]
   [input] Lookup Service to register Lookup Information [2] - this functionality will be disabled. To enable it uncomment the proper section in service.properties file.
   [input] LS Storage -- XML database type](http,xmlrpc)
  • choose http or xmlrpc. http is expermental but much faster. It should work without any problems as well. 
   [input] LS Storage -- XML database collection [3]
  • will be set automaticaly. Be sure to choose right protocol:// for your previous choice (http:// for http, exist:xmldb:// for xmlrpc) 
   [input] LS Storage -- XML database username [lookupservice]
   [input] LS Storage -- XML database password [sonar]
   [input] LS Cleanup -- enable LS Cleanup (removing old entries when TTL exceeded)?(y,n)
  • choose y if you want to enable LSCleanup 
   [input] LS Cleanup -- cleanup interval: how often to search old entries in DB [300] (seconds)
   [input] LS Cleanup -- TTL of lookup informationB [3600] (seconds)
   [input] Axis home directory (inside tomcat) [/usr/local/tomcat/webapps/axis]
[edit]

Compiling service

[edit]

Step 12 - Lookup Service compilation

After configuration (step 9) you may compile your sources now. Simply enter the following commands: 

 cd $PERFSONAR_LS/ant
 ant -f build-xmlls.xml build-xmlls


[edit]

Configuring Tomcat to run with Lookup Service

Before you proceed we assume you already have Tomcat and Axis correctly installed in your system. If you are going to run Lookup Service as another instance of the service on the same server follow these instructions how to change Tomcat and service ports first.

[edit]

Step 13 - catalina.properties

Editing catalina.properties file is very IMPORTANT. Without these settings, the Lookup Service will not work.

In your Tomcat location open file ./conf/catalina.properties and add the following lines indicating Lookup Service properties files locations: 

service.properties=$PERFSONAR_LS/conf/service.properties
components.properties=$PERFSONAR_LS/conf/components.properties

This step is very important: if you don't do it, Tomcat won't be able to load components of perfSONAR and you'll get #NullPointerException while running client application.

[edit]

Starting Web applications

[edit]

Step 14 - Running Tomcat

  • Execute the following command in Tomcat home directory in order to launch Tomcat 
$TOMCAT/bin>./startup.sh
  • Or restart Tomcat if it has been running previously 
$TOMCAT/bin>shutdown.sh
$TOMCAT/bin>startup.sh
[edit]

Step 15 - Deploying Lookup Service

  • Undeploy application from Tomcat (if necessary) 
 cd $PERFSONAR/ant
 ant -f build-xmlls.xml undeploy-xmlls
  • Deploy the Lookup Service in Tomcat 
 ant -f build-xmlls.xml deploy-xmlls
  • Restart your Tomcat 
$TOMCAT/bin>shutdown.sh
$TOMCAT/bin>startup.sh
  • If you want to validate your service installation follow those simple checks.
[edit]

Testing

It is presumed that you have completed all steps before. Now you can check whether Lookup Service deployment has been successful.

[edit]

Testing without Tomcat

You can test the functionality of LS without running Tomcat. There are test XML requests in $PERFSONAR_LS/schema/example-instances/sonar/LS/test/, and three Ant tasks for them:

  • LSRegisterRequest.xml - registers sample data within Lookup Service 
cd $PERFSONAR_LS/ant
ant -f build-xmlls.xml ls-test-register
  • LSQueryRequest.xml - sample XQuery 
cd $PERFSONAR_LS/ant
ant -f build-xmlls.xml ls-test-query
  • LSDeregisterRequest.xml - deregisters sample data (registered before by using LSRegisterRequest.xml) 
cd $PERFSONAR_LS/ant
ant -f build-xmlls.xml ls-test-deregister

They are passed directly (after translating to DOM) to the RequestHandler. They don't need Tomcat running.

[edit]

Testing with Tomcat

You can also run test client requests using following commands: 

cd $PERFSONAR_LS/ant
ant -f build-xmlls.xml ls-run-client-query
ant -f build-xmlls.xml ls-run-client-register
ant -f build-xmlls.xml ls-run-client-deregister

They run org.perfsonar.service.testHarness.MATestClient. They read input XML file and sends it through Axis to the perfSONAR application. To change the input filename, edit $PERFSONAR_LS/ant/ls-client-run-targets.xml.

Retrieved from "http://wiki.perfsonar.net/jra1-wiki/index.php/Installation_LS_snapshot_2006-09-19"
Personal tools