Installing Windows

Before installing the GRIA package on a Windows system, you will require the following:

• The Windows installation CD, Service Packs, etc.
• User with administrator privileges to install GRIA.

N.B. There are several ways to install and configure Windows, so you are advised to consult your system manager and set-up the system according to your needs.

This page explains how to install and configure all Windows prerequisites and how to configure the firewall.

Software Pre-requisites

The Windows distribution CD does not include several of the necessary packages. These are Java 6.x and Tomcat 5.5.x which must be installed separately. In addition if you are installing the GRIA Basic Application Services then Python is a pre-requisite and, optionally, if you wish to use the demo applications, ImageMagick version 6.0.x or later. The following sections describe how to install and configure these packages for Windows.

Java Installation

Download the SE Update for the Windows platform from Sun (the file will have the form jdk-6ux-windows-i586-p.exe). Double-click on the downloaded binary to run the installer, and during installation use the default values.

Tomcat installation

Download version 5.5.20 or higher of the Windows Service Installer Package.

Install Tomcat by double-clicking on the downloaded package e.g. apache-tomcat-6.0.x.exe. During installation use the default values, ensuring that:

• the path for JVM points to the SDK directory and NOT the JRE, e.g. C:\Program Files\Java\jdk1.6.0_06
• a password for the Tomcat admin account is provided.

Configuring the Firewall

The deployed GRIA war (or webapp) should be hosted behind a firewall to ensure that your server can only be accessed on certain ports. You should consult with your systems administrator to determine if you need to run a firewall on the GRIA server machine.

Windows XP by default runs a firewall which blocks ports 8080, and 8443. However, Windows 2003 Server by default does not run a firewall. If you decide to run a firewall on the machine hosting the GRIA services, you will need to open port 8080 and 8443 during installation. The firewall can be configured by: choosing the Windows Firewall from the Control Panel, then click on Exceptions -> Add Port and enter name and number:

• Tomcat, 8080 and leave transport protocol as TCP
• Tomcat (secure), 8443 and leave transport protocol as TCP

When you've finished setting up GRIA you can block port 8080 again.

Configuring NTP

In order to provide some synchronisation between the clocks on machines that the various GRIA packages are installed on, it is recommended to run an NTP client service that will synchronise your system with an Internet time server.

There are several NTP client implementations available, e.g. Meinberg's NTP client. If you decide to use this one, then during installation select the default options except for the "Configuration File Settings" dialogue. Here you should select an NTP server from the "Want to use predefined public NTP servers" drop-down list that is geographically located closest to you.

Starting Tomcat

The easiest way to control Tomcat on Windows is to use the Tomcat Monitor tool. This is available by selecting Start -> All Programs-> Apache Tomcat 5.5 -> Monitor Tomcat. Once it is started you will notice a new icon on your taskbar. Right-click on the icon to start and stop the tomcat service. If you want the tomcat service to automatically start on boot-up right-click on the icon and select "Configure". Then change startup type to "Automatic".

Introduction

This page explains how to install and configure all pre-requisites for OpenSUSE 11, configure a firewall on the GRIA server machine and set-up Tomcat for or deployment of a GRIA war.

Software Prerequisites

This page describes how the prerequisites for SuSE can be installed using the YaST systems configuration tool. They are as follows:

• The Java SDK v1.6.0 (6.0) or higher
  • java-1_6_0-sun
  • java-1_6_0-sun-devel
• Jakarta Tomcat 6
  
  • tomcat6-admin-webapps
  • tomcat6-webapps
• Apache Server v2.2 (an optional package to provide secure access)
  • apache2
  • apache2-prefork
  • apache2-mod_jk
    
• A web browser, such as Firefox (can be installed on a different machine)
  • MozillaFirefox
• A sample application (only required for the GRIA Basic Application Services package)
  • ImageMagick

You can use either Tomcat or Apache to provide secure access. If you are unsure then choose Tomcat as it is easier to set up.

In order to provide some synchronisation between the clocks on machines that the various GRIA packages are installed on, it is recommended that you run an NTP client that will synchronise your system with an Internet time server. Having installed the Linux base platform, configure the Network Services to use an NTP server. This is done as follows:

1. Run YaST and select 'Network Services'
2. From here, choose 'NTP Client' (or 'NTP Configuration') and select an NTP server, setting it to start on boot up. If you don't have an NTP server available on your local network then select a public one e.g. a.ntp.alphazed.net in Great Britain.

Having configured the machine to use NTP, the system should then be restarted to ensure the changes made during the installation of the above pre-requisites are applied.

This completes the installation of the GRIA software prerequisites.

Configuring the Firewall

The deployed GRIA war (or webapp) should be hosted behind a firewall to ensure that your server can only be accessed on certain ports. You should consult with your systems administrator to determine if you need to run a firewall on the machine hosting the GRIA webapp. If so, configure the firewall as follows:

1. Run YaST
2. Click on Security and Users.
3. Click on Firewall.
4. Select Interfaces from the menu and set interfaces appropriate to you network. You may need to discuss this with your systems administrator.
5. Select Allowed Services from the menu, then:
   • add a HTTPS server.
   • add a HTTP server.
   • Use the Advanced button to add TCP port 8080. If you intend to use Tomcat for secure access then also add port the 8443.
   • if you require Secure Shell access then also add SSH.
6. Click on Next and then Accept to finalise the settings.
7. Start the firewall.

Set-up Tomcat Users

In order to deploy the war file, the Tomcat Manager for application deployment will be used. The Tomcat manager functions are disabled by default.

To enable Tomcat administration and management we must add a role and a tomcat user to the tomcat-users.xml file.

1. Open the /etc/tomcat6/tomcat-users.xml file with a suitable editor and add this element, replacing ADMIN_PASSWORD with an appropriate password:

   <user username="admin" password="ADMIN_PASSWORD" roles="manager"/>
   

2. Save the file.

Start Tomcat

To start Tomcat:

$ su
# /etc/init.d/tomcat6 start

To stop Tomcat:

$ su
# /etc/init.d/tomcat6 stop

To restart Tomcat:

$ su
# /etc/init.d/tomcat6 restart

To get the status of Tomcat:

$ su
# /etc/init.d/tomcat6 status

Test it with your browser by pointing to your machine URL ( http://<host IP>:8080). You should be able to access your Tomcat server home page.

Initial system Configuration

There are several ways to install and configure Fedora, we advise consulting your system manager and setup the system according to your needs. In the following sections we describe a simple way to install all the necessary prerequisites for GRIA services on a Fedora system.

Firewall Configuration

For security reasons you should run a firewall. Check your firewall settings using the following command as root:

# system-config-firewall

Ensure in your firewall configuration that the following predefined ports: WWW, and Secure WWW are enabled. Additionally you need to add the following ports 8080 and 8443.

Click on other ports (section to expand) and use the add button to add new ports, type 8080 for the port number and select the protocol type as tcp. Repeat the same steps to add port 8443.

Click next and say yes to overwrite system settings.

SELinux Configuration

To start the configuration tool:

# system-config-selinux

Leave the default settings to Enforcing, then from the Modify SELinux Policy expand the HTTP Service Section and click on Allow HTTPD scripts and modules to connect to the network.

Date and Time

In order to provide some synchronisation between the clocks on machines that the various GRIA packages are installed on, we recommend running an NTP client service that will synchronise your system with an Internet time server. From the system settings choose Date and Time section choose the Network Time Protocol tab and click on the Enable Network Time Protocol button.

Installing the Software Pre-requisites

Having installed the operating system, the following lists the pre-requisites which must be installed if a GRIA service is to function correctly. It is important to install any dependencies which may also required by these software pre-requisites:

• Sun Java JDK v1.6 or higher (Java SE)
  
• Jakarta Tomcat v6.0.x
• or JBoss application server

The Fedora distribution include RPM packages for Tomcat and for GNU Java. However, to use GRIA you must install Sun Java. Unfortunately, it is very difficult to configure the pre-packaged Tomcat to use Sun Java, so Tomcat must also be manually installed by following the instructions below.

First, download the Java binary JDK selecting the "Linux self-extracting file" (e.g. jdk-1_5_0_05-linux-i586.bin) and Tomcat packages and place them into /tmp directory on the Fedora Core 5 machine. You may find it easiest to do this by downloading the packages to your desktop machine and copying them to the server. Finally, log in to the server machine as the root user ready to install the software.

Install Java

In order to install Java the following must be done (adjusting the version number to your particular package):

1. Move to /opt:

   # cd /opt

2. Unpack the binary from the temporary directory:

   # sh /tmp/jdk-1_5_x_xx-linux-i586.bin

3. Create a symbolic link within this directory:

   # ln -s jdk1.5.x_xx java

Install Tomcat

The following must be done in order to install Tomcat successfully (adjusting the version number to your particular package):

1. Tomcat will be installed under the /opt directory, therefore move to this directory with:

   # cd /opt

2. Unpack the Tomcat tarball from the temporary directory:

   # tar xvfz /tmp/apache-tomcat-5.5.xx.tar.gz

3. Create a symbolic link for Tomcat

   # ln -s apache-tomcat-5.5.xx tomcat

4. Tomcat will be most secure if it is not run by root, therefore create a user for the tomcat server to run as e.g. "tomcat" with the user's home directory set to /opt/tomcat:

   # system-config-users

   Create a new user called "tomcat" with a home directory of "/opt/tomcat".

5. Alter the ownership of the directory to the tomcat user created above:

   # chown -HR tomcat:tomcat tomcat

6. Configure tomcat to use Sun Java by editting /opt/tomcat/bin/catalina.sh. Open the file (e.g. in vi) and add the line JAVA_HOME=/opt/java to the top of the file after the file header, e.g.:

   # system class path used to start Tomcat.
   #
   # CATALINA_PID (Optional) Path of the file which should contains the pid
   # of catalina startup java process, when start (fork) is used
   #
   # $Id: fc4-pre.htm 3715 2006-04-10 14:01:19Z ajw $
   # -----------------------------------------------------------------------------
   
   JAVA_HOME=/opt/java
   
   # OS specific support. $var _must_ be set to either true or false.
   cygwin=false
   

Setting Up Tomcat Users

In order to deploy the war file, the Tomcat Manager for application deployment will be used. The Tomcat manager functions are disabled by default.

To enable Tomcat administration and management we must add a user with appropriate roles to the /opt/tomcat/conf/tomcat-users.xml file. Do this by adding the line:

<user username="tomcat" password="TOMCAT_PASSWORD" roles="admin,manager"/>

Starting Services

As mentioned above, Tomcat should not be run as root, therefore first switch form being the root user to the tomcat user and then start tomcat:

# su tomcat
$ cd /opt/tomcat/bin
$ ./startup.sh

Verify the installation by visiting http://localhost:8080 in your browser.

Installing Java

Run the following command to install sun-java6-jdk packages:

sudo apt-get install sun-java6-jdk

The system will prompt you to accept the DJK license, reply yes. You can test the installed java version in your system executing the following command:

$ java -version
java version "1.6.0_06"
Java(TM) SE Runtime Environment, Standard Edition (build 1.6.0_06-b02)
Java HotSpot(TM) Client VM (build 1.6.0_06-b22, mixed mode, sharing)

Installing tomcat5

Run the following command to install tomcat5.5 or tomcat6 packages:

$ sudo apt-get install tomcat5.5 tomcat5.5-admin tomcat5.5-webapps

or for tomcat6

$ sudo apt-get install tomcat6 tomcat6-admin tomcat6-webapps

During tomcat installation the system will install automatically an open version of Java as the default system java. In order to make Sun's java the default one run:

sudo update-alternatives --config java

Edit /etc/default/tomcat5.5, 6 to:

• define JAVA_HOME, e.g.
  

  JAVA_HOME=/usr/lib/jvm/java-6-sun

• replace line TOMCAT_SECURITY=yes with the following:
  

  TOMCAT_SECURITY=no

• configure JAVA_OPTS to

  JAVA_OPTS="-Djava.awt.headless=true -Xmx512m -Xms128m -XX:MaxPermSize=512m -jvm server"

Edit /var/lib/tomcat5.5/conf/tomcat-users.xml file to add a manager role, e.g.

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
   ...
   <role rolename="manager"/>
   <role username="manager" password="xxxxxx" roles="manager"/>
   ...
   </tomcat-users>

You need to restart tomcat now:

sudo /etc/init.d/tomcat5.5 restart

At this point refer to the GRIA documentation e.g. GRIA user guide, Deploying the Services to Tomcat.

NOTE: the default port for the tomcat server, for Ubuntu releases up to 8.10, is on 8180 NOT 8080, e.g. http://<servername>:8180

You can change the port number to 8080 if you want by editing /var/lib/tomcat5.5/conf/server.xml and changing the connector port="8180" settings.

Setting the system clock

In order to provide some synchronisation between the clocks on machines that the various GRIA packages are installed on, it is recommended that you run an NTP client service that will synchronise your system with an Internet time server. On Debian and Ubuntu systems, this can be done using the ntpdate or ntp packages, e.g. sudo apt-get install ntp.

Software Pre-requisites

The Mac OS X installation does not include some of the necessary packages. These are the Xcode Tools that have some optional Java utilities and Tomcat 5.5.x which must be installed. In addition if you are installing the GRIA Basic Application Services then Python is a pre-requisite and, optionally, if you wish to use the demo applications, ImageMagick version 6.0.x or later. The following sections describe how to install and configure these packages for Mac OS X.

Xcode Tools Installation (optional)

Insert the Mac OS X Installation Disc. A new finder window appears with the contents of the disc. Open the Xcode Tools folder and double click to install the XcodeTools.mpkg. During installation use the default options.

Tomcat installation

Download version 5.5.X  of the zip or tar.gz binary distribution.

Export the contents of the archive to the preferred directory.

Using the Terminal.app:

Edit /PathTo/apache-tomcat-5.5.X/conf/tomcat-users.xml file to add a manager role, e.g.

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
   ...
   <role rolename="manager"/>
   <role username="manager" password="xxxxxx" roles="manager"/>
   ...
   </tomcat-users>

cp /PathTo/commons-io-1.4.jar /PathTo/apache-tomcat-5.5.X/server/webapps/manager/WEB-INF/lib/

/PathTo/apache-tomcat-5.5.X/bin/startup.sh

At this point refer to the GRIA documentation e.g. GRIA user guide, Deploying the Services to Tomcat.

Deployment of the war file is based on the standard procedure which should already be familiar to Tomcat users. If, however, this is not the case then this section can be used as a guide on how to deploy and invoke the the web application. The home directory of Tomcat is denoted by <TOMCAT_HOME>

The next steps require the use of a web browser to complete the war file deployment.

1. Using a web browser, load the main Tomcat server page (e.g. http://<servername>:8080) and select the "Tomcat Manager" link.

   N.B. "<servername>" should be replaced with the IP address or fully qualified hostname of the computer running the Tomcat server.

   You will be prompted for a username and password to be entered before displaying the manager page. Use "admin" as the username and enter the password that was selected either by using the Tomcat installer (WinXP) or by editing the <TOMCAT_HOME>/conf/tomcat-users.xml (Linux) .

2. The page which loads once login has been successful presents the following sections:
   • Manager - lists the command controls and help functions
   • Applications - lists the applications currently deployed within Tomcat
   • Deploy - options for deploying applications to Tomcat
   • Server Information - lists specific information on Tomcat and the base platform it was installed to

   Scroll down to the WAR file to deploy subsection, within the Deploy section. Beside the "Select WAR file to upload" box, click the browse icon and select the war file, before clicking the "Deploy" button:

3. An "OK" message at the top of the page indicates that the war has been successfully deployed to Tomcat.

The new webapp should now also be listed within the Applications section. Note here in the last column is where individual applications may be started, stopped, reloaded or if desired undeployed completely from within Tomcat.

This completes the first part of the installation and deployment of the GRIA services.

Having successfully deployed the war file, you can invoke it by just clicking on the webapp's name in the Applications section.

If you get an error page with a message related to the JAVA_HOME environment variable, then this probably means that the Java compiler isn't working. The usual cause of this is trying to run tomcat immediately after installing Java. You must log out and log in again to ensure the JAVA_HOME environment variable is set to the correct location. If you click on the Admin link in the top menu when having this problem you will also get a 401 Not Authorized error without being prompted to log in (check for errors in the catalina.out log file).

Introduction

These instructions are applicable on both Linux and Windows and have been tested on JBoss Application Server 4.0.2 and later.

Procedure

There are two restrictions on deploying a GRIA service in JBoss:

1. JBoss must be installed in a directory that has no spaces in its path (for instance, not in C:\Program Files).
2. The GRIA war file must be deployed statically.

To describe how to deploy a GRIA service statically, we will take the example of the GRIA OGSA-DAI service being deployed in the default JBoss server.

GRIA services are supplied as war files. These are actually just zip archives. The service must be unzipped by hand but the directory that results must be renamed to end with the .war file extension:

1. Stop JBoss
2. Take the GRIA package, e.g. gria-ogsadai-service.war and place it in server/default/deploy.
3. Change the file extension from "war" to "zip" and unzip the package.
4. Rename the new directory from e.g. gria-ogsadai-service to gria-ogsadai-service.war.
5. Remove the zip file.
6. Start JBoss

Once the service has been deployed, navigate to the GRIA Service in your web browser (e.g. http://localhost:8080/gria-ogsadai-service). The GRIA installation wizard will then guide you through the rest of the configuration process.

Transport layer security (TLS) is the term used for encrypting the packets of information sent between the server and the client (and client and server).  It is also used to allow one side to verify the identity of the other party.  In a normal installation it is only the client who verifies the server's identity so that the client is sure that they are communicating with the service they intended to.

In a simple installation, a GRIA service is installed in Tomcat and Tomcat is configured to use TLS.  For extra flexibility and robustness many people want to use the Apache web server as a front end and pass requests on to Tomcat behind.  In this scenario Apache handles the encryption at the transport layer, but will pass requests on to Tomcat for processing.

For full details, see http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html.

Edit your Tomcat's conf/server.xml and add the following section (or uncomment and edit the existing one):

<Connector port="8443"
		keystoreFile="/your/location/here/service-keystore.ks"
		keystorePass="your_keystore_password"
		keystoreType="JKS"
		minProcessors="5" maxProcessors="75"
		enableLookups="true" disableUploadTimeout="true"
		acceptCount="100" debug="0" scheme="https" secure="true"
		clientAuth="false" sslProtocol="TLS"/>

Then restart Tomcat.

The file to edit in JBoss depends on the version. For JBoss 4.0.2 look in server/default/deploy/jbossweb-tomcat55.sar/server.xml file, but for JBoss 4.2.1.GA you must edit server/default/deploy/jboss-web.deployer/server.xml and add the following section (or uncomment and edit the existing one):

<Connector port="8443" address="${jboss.bind.address}"
    maxThreads="100" strategy="ms" maxHttpHeaderSize="8192"
    emptySessionPath="true"
    scheme="https" secure="true" clientAuth="false"
    keystoreFile="/path/to/your/keystore/service-keystore.ks"
    keystorePass="your_keystore_password"
    keystoreType="JKS" SSLEnabled="true"
    sslProtocol="TLS"/>

Then restart JBoss.