Installation Overview

The following steps highlight the HIEOS installation process (if you want to build and deploy from binary files, you shoud go to Binary Installation Guide):

This process is described in detail in upcoming sections.

1. Source code check-out
2. Database setup
3. Application server setup
4. IDE setup
5. Environment variable setup
6. Build and deployment
7. Validate and test the deployment

If you just want to test against an XCA and/or XDS.b implementation, please consult the following URL: http://208.81.185.143:8080/xwebtools.

Prerequisite Software

The prerequisite software for building and deploying HIEOS is summarized below:

Note: HIEOS has been tested under both Linux and Windows operating system environments. This guide currently assumes a Windows-based installation. A future version of this setup guide will more clearly delineate Windows vs. Linux configuration variations (e.g. environment variables, etc.)

Check-out Procedure

HIEOS’s distribution is available in a subversion repository at http://kenai.com/projects/hieos

1. Download and install a subversion client such as TortoiseSVN (http://tortoisesvn.tigris.org/) to be able to obtain HIEOS’s source.
2. Create a directory on your local file system to store the HIEOS source code. This location will be referred to as «HIEOS_ROOT» throughout this setup guide.
3. Go to http://kenai.com/projects/hieos and navigate to the link “Get Source Code” and copy the URL which should resemble https://kenai.com/svn/hieos~subversion/.
4. "Check-out" the trunk (main branch), or tagged release of the source code by entering the repository URL, https://kenai.com/svn/hieos~subversion/trunk/, in the subversion client.

Directory Structure Overview

A layout of the HIEOS distribution is described in the table below:

Source Code Project Structure

A description of the NetBeans projects contained in the «HIEOS_ROOT»\src directory are listed in the table below:

Database Setup

HIEOS has been tested with both MySQL and PostgreSQL relational database management systems and includes DDL and DML for these environments. To support its various functions, HIEOS requires that the following data stores be created:

In addition to creating each data store, the application server must be setup with designated connection pools (see Connection Pool Configuration).

MySQL Setup

This section describes the procedure for setting up HIEOS MySQL-based data stores.

Installation

Note: You can choose any ports/passwords, but you will need to note these as this guide assumes default ports, etc.

1. MySQL 5.1 Community Server (Windows MSI Installer (x86) version) can be downloaded from http://www.sun.com/software/products/mysql/getit.jsp
2. During the installation:
   1. Accept all default settings (port = 3306 etc.).
   2. Provide password: “admin” (user=”root” by default).
3. It is also recommended that GUI tools 5.x that contains MySQL Admin, Client Browser etc. be downloaded from http://dev.mysql.com/downloads/gui-tools/5.0.html

Configuration

1. Ensure that the MySQL Server is running
2. Connect to the MySQL Server (localhost: 3306) with credentials (root/admin) using the MySQL Administrator tool.
3. The first task is to create the required HIEOS data stores. On the left navigation pane, select “Catalogs”. This opens up a pane right below called “Schemata”. Right click on this pane and select “Create New Schema”.
   1. To create the “adt” data store
      1. Enter Schema name – "adt"
      2. Go to “Tools”->”MySQL Query Browser”
      3. In the Query Browser go to “File”->”Open Script”
      4. Select the DDL «HIEOS_ROOT»\data\adt\mysql\createadtddl.sql
      5. Hit Execute
   2. To create the “log” data store
      1. Enter Schema name – “log”
      2. Go to “Tools”->”MySQL Query Browser”
      3. In the Query Browser go to “File”->”Open Script”
      4. Select the DDL «HIEOS_ROOT»\data\log\mysql\createlogddl.sql
      5. Hit Execute
   3. To create the “repo” data store
      1. Enter Schema name – “repo”
      2. Go to “Tools”->”MySQL Query Browser”
      3. In the Query Browser go to “File”->”Open Script”
      4. Select the DDL «HIEOS_ROOT»\data\repo\mysql\createrepoddl.sql
      5. Hit Execute
   4. To create the “omar” data store
      1. Enter Schema Name – “omar”
      2. Go to “Tools”->”MySQL Query Browser”
      3. In the Query Browser go to “File”->”Open Script”
      4. Select the DDL «HIEOS_ROOT»\data\registry\mysql\createregistryddl.sql
      5. Hit Execute
      6. Similarly, load the seed data script «HIEOS_ROOT»\data\registry\common\loadseedregistrydbddl.sql
      7. Select the database “omar” in the Schemata pane of the Query Browser
      8. Hit Execute
4. The next task is to provide access to the created data stores. On the left navigation pane, select “User Administration”. This opens up a pane right below called “User Accounts”. Right click on this pane and select “Add new User”. A view is presented on the right pane to enter user information.
   1. To create access credentials for the "adt" data store
      1. Enter MySQL User/Password – adt/xdsadt
      2. Select the schema privileges tab and assign ‘SELECT’, ‘INSERT’, ‘UPDATE’ and ‘DELETE’ privileges against schemata “adt”, and hit “Apply Changes”
      3. In the User Accounts Pane, right click on “adt” -> “Add host from which the user can connect”
      4. Enter “localhost” and hit “Apply Changes”
   2. To create access credentials for the "log" data store
      1. Enter MySQL User/Password – log/xdslog
      2. Select the schema privileges tab and assign ‘SELECT’, ‘INSERT’, ‘UPDATE’ and ‘DELETE’ privileges against schemata log, and hit ‘Apply Changes’.
      3. In the User Accounts Pane, right click on “log” -> “Add host from which the user can connect”
      4. Enter “localhost” and hit “Apply Changes”
   3. To create access credentials for the "repo" data store
      1. Enter MySQL User/Password – repo/xdsrepo
      2. Select the schema privileges tab and assign ‘SELECT’, ‘INSERT’, ‘UPDATE’ and ‘DELETE’ privileges against schemata repo, and hit ‘Apply Changes’
      3. In the User Accounts Pane, right click on “repo” -> “Add host from which the user can connect”
      4. Enter “localhost” and hit “Apply Changes”
   4. To create access credentials for the "omar" data store
      1. Enter MySQL User/Password – omar/omar
      2. Select the schema privileges tab and assign ‘SELECT’, ‘INSERT’, ‘UPDATE’ and ‘DELETE’ privileges against schemata omar, to this user and hit ‘Apply Changes’
      3. In the User Accounts Pane, right click on “omar” -> “Add host from which the user can connect”
      4. Enter “localhost” and hit “Apply Changes”

PostGres Setup

This section describes the procedure for setting up HIEOS PostGres-based data stores.

Installation

Note: You can choose any ports/passwords, but you will need to note these as this guide assumes default ports, etc.

1. PostgreSQL 8.X can be downloaded from http://www.postgresql.org/download/. The core distribution contains the "pgadmin" administration tool that is referenced in this setup guide.
2. During installation:
   1. Accept all default settings (ex: port = 5432)
   2. Provide password. PostgreSQL requires that a complex password be used (Ex: adminadmin123X, user = postgres by default)

Configuration

1. Connect to the PostGres server using the "pgadmin" tool
2. The first task is to create access roles by going to the object browser and clicking on “Login Roles” -> “New Login Role”
   1. Role Name/Password – adt/xdsadt with all role privileges except Super user
   2. Role Name/Password – log/xdslog with all role privileges except Super user
   3. Role Name/Password – repo/xdsrepo with all role privileges except Super user
   4. Role Name/Password – omar/omar with all role privileges except Super user
3. The next task is to create the following databases (in the default table space for now) by going to the object browser and clicking on “Databases” -> “New Database”
   1. To create the “adt” data store
      1. Enter “Name” – “adt”
      2. Set “owner” – “adt” and hit “OK”
      3. Select the database “adt” in the object browser
      4. Go to “Tools”->”Query Tool”
      5. In the Query Tool go to “File”->”Open”
      6. Select the DDL «HIEOS_ROOT»\data\adt\postgres\createadtddl.sql
      7. Hit Execute
   2. To create the “log” data store
      1. Enter “Name” – “log”
      2. Set “owner” – “log” and hit “OK”
      3. Select the database “log” in the object browser
      4. Go to “Tools”->”Query Tool”
      5. In the Query Tool go to “File”->”Open”
      6. Select the DDL «HIEOS_ROOT»\data\log\postgres\createlogddl.sql
      7. Hit Execute
   3. To create the “repo” data store
      1. Enter “Name” – “repo”
      2. Set “owner” – “repo” and hit “OK”
      3. Select the database “repo” in the object browser
      4. Go to “Tools”->”Query Tool”
      5. In the Query Tool go to “File”->”Open”
      6. Select the DDL «HIEOS_ROOT»\data\repo\postgres\createrepoddl.sql
      7. Hit Execute
   4. To create the “omar” data store
      1. Enter “Name” – “omar”
      2. Set “owner” – “omar” and hit “OK”
      3. Select the database “omar” in the object browser
      4. Go to “Tools”->” Query Tool”
      5. In the Query Tool go to “File”->”Open”
      6. Select the DDL «HIEOS_ROOT»\data\registry\createregistryddl.sql
      7. Hit Execute
      8. Similarly, load the seed data script «HIEOS_ROOT»\data\registry\common\loadseedregistrydbddl.sql
      9. Hit Execute

Application Server Setup

GlassFish was chosen as the application server for the HIEOS project. The SOAP stack is being provided by Axis2.

JDK Installation

1. Download and install JDK 1.6.x http://www.sun.com/download/index.jsp
2. Add the JDK bin directory to the PATH environment variable

GlassFish Installation

Note: You can skip to the IDE Setup and use Glassfish v2.1 bundled with NetBeans.

1. Download GlassFish v2.1 from https://glassfish.dev.java.net/public/downloadsindex.html#top
2. During installation, note the directory where GlassFish will be installed. It will be referred to as the «GLASSFISH_HOME» directory in the remainder of this setup guide.
3. Also note that the correct JDK (see step 1 in JDK Installation) is being referenced
4. Accept all default properties

Axis2 Installation

1. Download Axis2 v1.4.1 (WAR distribution) from http://ws.apache.org/axis2/download.cgi The distribution is a zip file.
2. Extract axis2.war from the zip file and copy it to «GLASSFISH_HOME»\domains\domain1\autodeploy

Connection Pool Configuration

Data sources associated with HIEOS data stores need to be registered with the application server to leverage benefits provided by database connection pooling. These data sources should then be associated with JNDI names thereby rendering them accessible in the application server’s JNDI namespace. HEIOS depends on these JNDI names to connect to the various HIEOS data sources.

Data Source Setup

Based on the RDBMS chosen, the appropriate set of configuration instructions described in this section should be followed.

MySQL Configuration

1. Copy the JDBC driver JAR file, «HIEOS_ROOT»\lib\mysql-connector-java-5.0.8-bin.jar, to «GLASSFISH_HOME»\domains\domain1\lib\ext
2. Restart GlassFish and log on to the admin console (e.g. http://localhost:4848)
3. Set up connection pools by going to Resources->JDBC->Connection Pool
   1. For the "adt" data store
      1. Select “New”
      2. Enter Name: hieos-adt-pool
      3. Enter Resource Type: javax.sql.ConnectionPoolDataSource
      4. Enter Vendor: MySQL
      5. Click “Next”
      6. Delete all properties from the “Additional Properties section” except Password, Url and User
      7. Set User: adt, Password: xdsadt
      8. Set Url: jdbc:mysql://localhost:3306/adt
      9. Click “Finish”
      10. Select the newly created connection pool and click “Ping”
   2. For the "log" data store
      1. Select “New”
      2. Enter Name: hieos-log-pool
      3. Enter Resource Type: javax.sql.ConnectionPoolDataSource
      4. Enter Vendor: MySQL
      5. Click “Next”
      6. Delete all properties from the “Additional Properties section” except Password, Url and User
      7. Set User: log, Password: xdslog
      8. Set Url: jdbc:mysql://localhost:3306/log
      9. Click “Finish”
      10. Select the newly created connection pool and click “Ping”
   3. For the "omar" data store
      1. Select “New”
      2. Enter Name: hieos-registry-pool
      3. Enter Resource Type: javax.sql.ConnectionPoolDataSource
      4. Enter Vendor: MySQL
      5. Click “Next”
      6. Delete all properties from the “Additional Properties section” except Password, Url and User
      7. Set User: omar, Password: omar
      8. Set Url: jdbc:mysql://localhost:3306/omar
      9. Click “Finish”
      10. Select the newly created connection pool and click “Ping”
   4. For the "repo" data store
      1. Select “New”
      2. Enter Name: hieos-repo-pool
      3. Enter Resource Type: javax.sql.ConnectionPoolDataSource
      4. Enter Vendor: MySQL
      5. Click “Next”
      6. Delete all properties from the “Additional Properties section” except Password, Url and User
      7. Set User: repo, Password: xdsrepo
      8. Set Url: jdbc:mysql://localhost:3306/repo
      9. Click Finish.
      10. Select the newly created connection pool and click “Ping”

PostGres Configuration

1. Copy the JDBC driver JAR file, «HIEOS_ROOT»\lib\postgresql-8.3-604.jdbc4.jar, to «GLASSFISH_HOME»\domains\domain1\lib\ext
2. Restart GlassFish and log on to the admin console (e.g. http://localhost:4848)
3. Set up connection pools by going to Resources->JDBC->Connection Pool
   1. For the "adt" data store
      1. Select “New”
      2. Enter Name: hieos-adt-pool
      3. Enter Resource Type: javax.sql.ConnectionPoolDataSource
      4. Enter Vendor: PostgreSQL
      5. Click “Next”
      6. Delete all properties from the “Additional Properties section” except User, Password, ServerName, DatabaseName and PortNumber
      7. Set User: adt, Password: xdsadt
      8. Set DatabaseName: adt, ServerName: localhost, PortNumber: 5432
      9. Click “Finish”
      10. Select the newly created connection pool and click “Ping”
   2. For the "log" data store
      1. Select “New”
      2. Enter Name: hieos-log-pool
      3. Enter Resource Type: javax.sql.ConnectionPoolDataSource
      4. Enter Vendor: PostgreSQL
      5. Click “Next”
      6. Delete all properties from the “Additional Properties section” except User, Password, ServerName, DatabaseName and PortNumber
      7. Set User: log, Password: xdslog
      8. Set DatabaseName: log, ServerName: localhost, PortNumber: 5432
      9. Click “Finish”
      10. Select the newly created connection pool and click “Ping”
   3. For the "omar" data store
      1. Select “New”
      2. Enter Name: hieos-registry-pool
      3. Enter Resource Type: javax.sql.ConnectionPoolDataSource
      4. Enter Vendor: PostgreSQL.
      5. Click “Next”
      6. Delete all properties from the “Additional Properties section” except User, Password, ServerName, DatabaseName and PortNumber
      7. Set User: omar, Password: omar
      8. Set DatabaseName: omar, ServerName: localhost, PortNumber: 5432
      9. Click “Finish”
      10. Select the newly created connection pool and click “Ping”
   4. For the "repo" data store
      1. Select “New”
      2. Enter Name: hieos-repo-pool
      3. Enter Resource Type: javax.sql.ConnectionPoolDataSource
      4. Enter Vendor: PostgreSQL
      5. Click “Next”
      6. Delete all properties from the “Additional Properties section” except User, Password, ServerName, DatabaseName and PortNumber
      7. Set User: repo, Password: xdsrepo
      8. Set DatabaseName: repo, ServerName: localhost, PortNumber: 5432
      9. Click “Finish”
      10. Select the newly created connection pool and click “Ping”

JNDI Connection Pool Configuration

Once connection pools are setup for required HIEOS data stores, they must be associated with JNDI names as shown below:

You will set up the HIEOS JNDI configuration by going to Resources->JDBC->JDBC Resources

1. For the “hieos-adt-pool” connection pool
   1. Select “New”
   2. Set JNDI Name: jdbc/hieos-adt, Pool Name: hieos-adt-pool
   3. Click “OK”
2. For the “hieos-log-pool” connection pool
   1. Select “New”
   2. Set JNDI Name: jdbc/hieos-log, Pool Name: hieos-log-pool
   3. Click “OK”
3. For the “hieos-registry-pool” connection pool
   1. Select “New”
   2. Set JNDI Name: jdbc/hieos-registry, Pool Name: hieos-registry-pool
   3. Click “OK”
4. For the “hieos-repo-pool” connection pool
   1. Select “New”
   2. Set JNDI Name: jdbc/hieos-repo, Pool Name: hieos-repo-pool
   3. Click “OK”

IDE Setup

NetBeans 6.7.1 was chosen as the IDE for development of the HIEOS project.

NetBeans Installation

1. Download NetBeans 6.7.1 (IDE bundle “All”) from http://www.netbeans.org/downloads/index.html
2. During installation ensure that it is pointing to the downloaded JDK
3. Accept all default properties

NetBeans/GlassFish Integration

NetBeans can be integrated with GlassFish. This enables deployment, debugging, lifecycle control etc. of the GlassFish server from inside NetBeans.

1. Start NetBeans and click on “Services”
2. Right click on “Servers”->”Add Server”
3. Choose “GlassFish v2.x” as the server type and provide a unique server name. Ex: Glassfish v2.1
4. In the “Platform Location” entry box enter the directory where the Glassfish was installed. i.e. «GLASSFISH_HOME»
5. Accept the other default properties
6. Enter userid/password as admin/adminadmin

NetBeans/Axis2 Integration

1. In NetBeans, go to Tools->Plugins and install Axis2 plugin support
2. Shutdown and restart NetBeans to see Axis2 under “Tools”->”Options”
3. In “Tools”->”Options”->”Axis2”, set target location for Axis2 to «GLASSFISH_HOME»\domains\domain1\autodeploy\axis2.war

Configuration Files

XML-based configuration files are used to control the behavior of HIEOS at run-time. For a description of these files, please refer to Configuration Files.

Environment Variable Setup

The following environment variables are required for functioning of HIEOS. Under Windows, add the following environment variables by going to "My Computer -> Properties -> Advanced -> Environment Variables":

Once the above variables have been set, set “PATH=%PATH%;%HIEOSxTestDir%;” to enable execution of xtest from any location. Note: NetBeans and/or GlassFish should be restarted once these environment variables have been established.

Build and Deployment Steps

This section describes how to build the various HIEOS components from within NetBeans and then deploy these components to the GlassFish environment.

Build Steps

The following projects should be opened in NetBeans and built in the order below:

1. omar
2. xutil
3. adt
4. xclient
5. xwebtoolsconfig
6. xtest
7. logbrowser
8. xlogmdb
9. xlog
10. xwebtools
11. xref
12. xds
13. xca

Deployment Steps

The following artifacts should be deployed to GlassFish, either directly from inside NetBeans or through the GlassFish admin console. These instructions relate to deployment from inside NetBeans:

1. Start the server, by clicking on Services->Servers->GlassFish v2.1->Start
2. Deploy "xref"
   1. Right click xref->properties->Run and ensure “Server=GlassFish v2.1” and “Context Path=/xref”
   2. Right click xref ->Deploy
3. Deploy "logbrowser"
   1. Right click logbrowser->properties->Run and ensure “Server=GlassFish v2.1” and “Context Path=/logbrowser”
   2. Right click logbrowser->Deploy
4. Deploy "xwebtools"
   1. Right click logbrowser->properties->Run and ensure “Server=GlassFish v2.1” and “Context Path=/xwebtools”
   2. Right click xwebtools ->Deploy
5. Deploy "xlog"
   1. Right click xlog ->properties->Run and ensure “Server=GlassFish v2.1”
   2. Right click xlog ->Deploy
6. Deploy "xca"
   1. Right click xca -> Axis2 Web Services ->Deploy to Server
7. Deploy "xds"
   1. Right click xds -> Axis2 Web Services ->Deploy to Server

TLS Configuration

Transport Layer Security (TLS) is used to encrypt XDS.b and XCA web services transactions. As a part of the HIEOS distribution, the following directories are included to support the test client, "xtest" (TLS is enabled using the xtest -S command line option), and the HIEOS platform running under the GlassFish application server, to interact over TLS.

1. Sample certificates and keys under «HIEOS_ROOT»\certs
2. A keystore under «HIEOS_ROOT»\src\xtest\test\keystores to support "xtest"

The following configuration steps demonstrate how "xtest" and HIEOS should be setup for 2-way, TLS authentication. To setup HIEOS in live environments, please follow the same sequence of steps with CA issued certificates instead of the sample certificates provided by HIEOS.

Prerequisite Software

Install OpenSSL software (location = http://www.openssl.org/); OpenSSL will be used to transform X.509 certificates into PKCS#12 format which is a portable format that stores certificates, root certificate, private key all in a single file.

1. Go to: http://www.slproweb.com/products/Win32OpenSSL.html for the Windows binary. We chose Win32OpenSSL0.9.8k.
2. We also chose to have the installation deploy DLLs into OpenSSL’s bin directory as opposed to System32
3. Add OpenSSL’s bin directory to the Path environment variable

Note: (under Windows): if prompted, download Microsoft Visual C++ Redistributable from the same location and install it

GlassFish Configuration

1. The default keystore location for GlassFish is at «GLASSFISH_HOME»\domains\domain1\config\keystore.jks. This file contains the private key.
2. The default trust store location for GlassFish is at «GLASSFISH_HOME»\domains\domain1\config\cacerts.jks. This file contains the public certificates that need to be trusted.
3. The default password for both is "changeit". [This is the default GlassFish setup]
4. Make a back up of both these files
5. Copy the following files below to the location «GLASSFISH_HOME»\domains\domain1\config:
   1. «HIEOS_ROOT»\certs\hieos_test_server_key.pem
   2. «HIEOS_ROOT»\certs\hieos_test_client_cert.pem
   3. «HIEOS_ROOT»\certs\hieos_test_server_cert.pem
6. Clear the keystore (keystore.jks) and truststore (cacerts.jks) in GlassFish:
   1. First navigate to the directory (from the command line): «GLASSFISH_HOME»\domains\domain1\config
   2. Delete the existing certificate from the GlassFish keystore, keystore.jks, by the following command:
      » keytool -delete -alias s1as -keystore keystore.jks [enter password “changeit” when requested]
   3. Validate the deletion with the following command:
      » keytool -list -v -keystore keystore.jks [enter password “changeit” when requested; you should see 0 entries returned]
   4. Similarly delete the certificate from the GlassFish trust store, cacerts.jks by the following command:
      » keytool -delete -keystore cacerts.jks -alias s1as
   5. Double check with the following command:
      » keytool -list -v -keystore cacerts.jks -alias s1as [should get an exception message]
7. Transform HIEOS X509 certificates to pkcs#12 format:
   1. When in «GLASSFISH_HOME»\domains\domain1\config, execute “openssl”, this should present an “OpenSSL” prompt
   2. On the prompt, execute the following commands:
      1. OpenSSL> pkcs12 -export -out my_keystore.pkcs12 -in hieos_test_server_cert.pem –inkey hieos_test_server_key.pem
         1. You should get the message Loading 'screen' into random state – done
         2. Enter Export Password: changeit (this will be invisible)
         3. Verifying - Enter Export Password:changeit (this will be invisible)
      2. OpenSSL> exit
   3. A file called my_keystore.pkcs12 would have been created
8. Import the pkcs#12 certificate into keystore.jks
   1. Ensure you are in «GLASSFISH_HOME»\domains\domain1\config and issue the command:
      » keytool -importkeystore -deststorepass changeit -destkeystore keystore.jks -srckeystore my_keystore.pkcs12 -srcstoretype PKCS12 -srcstorepass changeit [You should see, "Import command completed: 1 entries successfully imported, 0 entries failed or cancelled"]
   2. The above command will create a default alias of "1". We need to change it to alias "s1as" which is GlassFish default with the following command:
      » keytool -keystore keystore.jks -storepass changeit -changealias -alias 1 -destalias s1as
9. Import the public keys (hieos_test_client_cert.pem and hieos_test_server_cert.pem) for "xtest" into the trust store by the commands:
   » keytool -import -noprompt -trustcacerts -file hieos_test_client_cert.pem -keystore cacerts.jks -alias client [The password is changeit; you should see a message "Certificate was added to keystore”]
   » keytool -import -noprompt -trustcacerts -file hieos_test_server_cert.pem -keystore cacerts.jks -alias s1as [The password is changeit; you should see a message “Certificate was added to keystore”]
10. Enable client side authentication for 2-way SSL (TLS) from within GlassFish admin console
    1. Go to http://localhost:4848/login.jsf
       1. User: admin
       2. Password: adminadmin
    2. On left of screen, go to Configuration -> HTTP Service -> HTTP Listeners
       1. Select “http-listener-2” [the one with port 8181]
       2. Go to SSL tab and check the option "Client Authentication"
       3. Select “Save”
    3. Be sure to restart the server [in NetBeans or otherwise]