Opal Installation Guide

Contents of this Guide

Introduction

Opal is an application that runs on a server. Users access it on client workstations via a secured shell connection over a network.

This guide is for whoever will set up Opal--typically, a system administrator.

The guide covers hardware and software requirements and includes procedures for deploying Opal on a server and setting up the client workstations.

Hardware Requirements

Server Hardware Requirements

Client Hardware Requirements

Software Requirements

Server Software Requirements

You must install the following software on the Opal server.

Client Software Requirements

You must have a SSH client installed on each Opal client. The recommended one for windows is PuTTY:

Installation and Execution Environment

Opal is distributed as a zip file. To install Opal, proceed as follows:

1. Download Opal distribution from here.
2. Unzip the Opal distribution. Note that the zip file contains a root directory named opal-server-1.1.0. You can copy it wherever you want. You can also rename it. The content of this zip file is:
   • bin: server startup scripts.
   • lib: various libraries required by Opal.
   • conf: configuration directory, the Opal "home" will refer to the parent directory.
3. Separate configuration and binaries directories (optional): with Opal 1.1 it is possible to install at different places:
   • the configuration directory (conf),
   • the binaries directories (bin and lib).
4. Configure the following environment variables:

   Environment variable	Required	Description
   JAVA_HOME	yes	Path to the Java installation directory. For example (Windows): C:\Program Files\Java\jre1.6.0_16
   JAVA_OPTS	no	Options for the Java Virtual Machine. For example: -Xmx4096m -XX:MaxPermSize=256m
   OPAL_HOME	yes	Path to the Opal "home" (configuration and logs) directory. For example (Windows): C:\opal-server-1.1

5. Configure the Users Authentication Directories. See Users Authentication Directories Configuration.
6. Configure the Database Accesses: see Database Configuration.
7. Configure the SSH Server: see SSH Server Configuration
8. Configure the File System Root: see File System Root
9. Run Opal Upgrade Command. This step will create/update the database schema for Opal: see Upgrade Command
10. Run Opal Server: see Launching Opal Server
11. Start a Opal Console to check every thing is up and running: see Starting Opal Console.

Users Authentication Directories Configuration

The security framework that is used by Opal for authentication, authorization etc. is Shiro. The configuration of Shiro for Opal is done via the file conf/shiro.ini.

More information about how to configure Shiro using the INI file can be found here. Support of LDAP, although announced by Shiro, is not yet implemented.

Default configuration is a static user 'administrator' with password 'password'.

Opal Base Configuration File

The file conf/opal-config.properties is to be edited to match your server needs.

Database Configuration

Opal is made of two distinct databases: one for the holding the participants identification keys and another one for holding the variable catalogue and participant data. Opal must have access to both databases. Defining a different database user for each of these databases ensures the participant data privacy.

Configuration file edition

The database configuration properties in conf/opal-config.properties must be edited to fit your environment. Currently there are examples for MySQL. Comment out and uncomment the appropriate lines for your configuration. Edit the properties to what is configured for your system. For example the username and password properties have to be changed for your environment.

For more information on how to configure the datasource, follow this link about Hibernate JDBC.

Database for data:

Database for keys:

Database creation

Create the above configured Opal schemas (for the 'opal' and 'key' databases) on your database system(s).

Make sure the corresponding database users are granted all privileges on their respective database instances (CREATE TABLE, ALTER, and so on).

MYSQL

The required MySQL JAR files are already deployed within the .zip file.  All you need to do to use MySQL is to make the configuration changes as described above.

At the time of writing this document, MySQL 5.1.x is recommended.

HSQL

HSQL is a Java implementation of an RDBMS. It has the ability to be embedded inside another application: it does not require a server running an previously installed instance. As such, it is a great candidate for testing a deployment. It is not recommended for production environments.

The required HSQL JAR files are already deployed within the downloaded package. All you need to do to use HSQL is to configure the settings as described above.
For information on hibernate.dialect: follow this link for a list of available Hibernate dialects.
HSQL jdbc url's are described here.

Other Databases

It is possible to configure other databases such as Oracle but because they have not been tested they will not be discussed here until the need arises.

SSH Server Configuration

Opal is accessible using SSH clients. Some settings of the server are configurable through the configuration files. By default the configuration key is commented. If the default value (8022) suits you, it is not necessary to uncomment it.

Opal Main Configuration File

The file conf/opal-config.xml is to be edited to match some of your server needs. The content of this file is described with more details in the Opal Configuration Guide. The installation guide describes only what is required for running a basic Opal server.

File System Root

Opal offers a "file system" in which users may manipulate files without having a user defined in the OS running Opal. That is, all interactions with the underlying file-system go through a unique system-user: the one that runs the Opal server.

The Opal file system root needs to be specified before running Opal. This is done in the conf/opal-config.xml file by setting the following statement:

Several types of file root names are recognized:

• Absolute URI. These must start with a scheme, such as 'file:', followed by a scheme dependent file name. For example:

  • file:/c:/dir/somedir

• Absolute local file name. For example, /home/someuser/somedir or c:\dir\somedir. Elements in the name can be separated using any of the following characters: /, \, or the native file separator character. For example, the following file names are the same:

  • c:\dir\somedir

  • c:/dir/somedir

Executing Opal

Upgrade Command

Running this command is required to create/upgrade the database schema, either when installing Opal for the first time or upgrading Opal from a previous version.

Simply run the following command:

• Windows console:

  opal.bat --upgrade

• Unix shell:

  opal --upgrade

The upgrade command can be executed safely several times.

Launching Opal Server

The Opal server can be launched from the command line (ensure bin directory is in your execution PATH):

• Windows console:

  opal.bat

• Unix shell:

  opal

Opal Server Logs

The Opal server log files are located in OPAL_HOME/logs directory, aside of the conf directory. If not existing it is created by Opal.

Starting Opal Console

Once server is started, try to access it using a SSH client. See Starting Opal Console in the User Guide for more details.

Search Opal Documentation