Metrics Installation

Installation

Dependencies

Listed below are the installation dependencies for the Metrics Service:

• Java 1.6 or higher
• Relational Database Management System. The Metrics Service currently ships with an in-memory HyperSQL (HSQLDB) database for testing and development purposes, but it is expected that a live deployment will use a more robust RDBMS such as Oracle or MySQL.

Metrics Service Bundle Description

The distribution of the Metrics Service bundle consists of a .zip file containing the necessary components to set up and run the Metrics Service in a development environment. The bundle contains the following:

• Tomcat-7.0.21 (Simple Java Web Container)
• Sample PKI Certificates for SSL (user and server)
• Metrics Service Web application (Metrics.war)
• Central Authentication Service application (cas.war)
• Externalized Security Configurations:
  • MetricSecurityContext.xml
  • MetricSecurityContext_cert_ldap.xml
  • MetricSecurityContext_cert_only.xml
• Tomcat start scripts (start.sh or start.bat)
• Four configurable externalized properties files:
  • MetricsConfig.groovy
  • CASSpringOverrideConfig.xml
  • OzoneConfig.properties
  • Metrics-override-log4j.xml

The following example shows how an administrator might copy, unzip and start the Metrics Service from the bundle deployment on *nix operating systems, assuming the bundle is name Metrics-bundle-7-GA.zip:

    cp Metrics-bundle-7-GA.zip/opt/.
    cd /opt

    unzip Metrics-bundle-7-GA.zip
    cd apache-tomcat-7.0.21
    ./start.sh

The following example shows how an administrator might copy, unzip, and start the Metrics Service from the bundle on Windows operating systems, assuming the bundle is named Metrics-bundle-7-GA.zip:

1. Create a new directory from where the Metrics Service will be run. This can be done via the Windows UI or the command prompt.
2. Copy Metrics-bundle-7-GA.zip to the new directory created in step 1.
3. Unzip the Metrics-bundle-7-GA.zip file.
4. From a command-line, run start.bat from within the apache-tomcat-7.0.21 directory.

The use of the bundled deployment archive provides all of the necessary mechanisms to deploy and run the Tomcat Web container on any Java 1.6+ enabled system.

Default Installation

Running the Metrics Service bundle via the included Tomcat Web server with the default values requires minimal installation. With standard configuration, the Metrics Service makes use of the default authentication module, which provides X.509 authentication/authorization, with CAS as a fallback if the framework cannot authenticate the user via certificates installed in their browser.

The application uses a keystore and a truststore which are local to the installation. There is no need to install any certificates into the server’s Java installation. The default certificates contained in the Metrics Service bundle only function for localhost communications. When accessed from a remote machine with a name that differs from localhost and while using the included certificates, the Metrics Service will not function correctly.

Installing User PKI Certificates

By default, the security infrastructure of the Metrics Service bundle is configured to use client certificates with CAS fallback. In order to identify themselves via certificates, clients need to install a PKI certificate into their Web browser. The client certificates that are included with the Metrics Service bundle will be recognized immediately and can be used in the default security configuration. The certificates are located in the \apache-tomcat-7.0.21\certs directory of the Metrics Bundle.

The default client certificates can be used by importing the included testUser1.p12 or testAdmin1.p12 certificate into the user’s browser. In Internet Explorer, client certificates can be added by selecting Tools → Internet Options → Content → Certificates → Personal, and then clicking the Import button. The certificate testUser1 grants rights to use the application, while testAdmin1 is a certificate for a user granted both user rights and administrator rights. The private key password for both certificates is password.

In Firefox this menu is accessed by selecting: Tools → Options → Advanced → Encryption → View Certificates → Your Certificates → Import.

Custom Installation

The Metrics Service can be customized to run in a variety of environments. The following sections detail how to change default database settings and set up security.

Database Setup

While the full extent of administering the following databases is outside the scope of this guide, this section provides information on how to work with databases for the Metrics Service.

MetricsConfig.groovy is a configuration file that allows an administrator to modify database connectivity information. It is located in the \apache-tomcat-7.0.21\lib directory. Once changes are made, restart the system to apply them. Developers comfortable with the Groovy language and the Grails application framework should be comfortable writing additional code for the file.

Listed below are the variable database properties that need to be modified to customize the Metrics Service database. A detailed explanation of each field follows:

    dataSource {
        pooled = true
        dbCreate = "none"
        username = "sa"
        password = ""
        driverClassName = "org.hsqldb.jdbcDriver"
        url = "jdbc:hsqldb:file:MetricsDb;shutdown=true"
        pooled = true
        properties {
            minEvictableIdleTimeMillis = 180000
            timeBetweenEvictionRunsMillis = 180000
            numTestsPerEvictionRun = 3
            testOnBorrow = true
            testWhileIdle = true
            testOnReturn = true
            validationQuery = "SELECT 1 FROM INFORMATION_SCHEMA.SYSTEM_USERS"
        }
    }

Table: Metrics Service Database Properties

Property	Purpose	Example
`dbCreate`	The way the database is created or updated upon server start NOTE: The appropriate database script should be used to create the database, so this property should always be set to “none”. Details on which script to run can be found in the individual database instructions below.	“none”
`username`	The username for the database connection	“admin”
`password`	The password for the database connection	"password"
`driverClassName`	JDBC driver	“org.hsqldb.jdbcDriver”
`URL`	JDBC Connection String	“jdbc:hsqldb:file:MetricsDb; shutdown=true”
`pooled`	Enable database connection pooling when true	true
`minEvictableIdleTimeMillis`	Minimum amount of time in milliseconds an object can be idle	“18000”
`timeBetweenEvictionRunsMillis`	Time in milliseconds to sleep between runs of the idle object evictor thread	“18000”
`numTestsPerEvictionRun`	Number of objects to be examined on each run of idle evictor thread	“3”
`testOnBorrow`	When true objects are validated before borrowed from the pool	true
`testWhileIdle`	When true, objects are validated by the idle object evictor thread	true
`testOnReturn`	When true, objects are validated before returned to the pool	true
`validationQuery`	Validation query, used to test connections before use	“SELECT 1 FROM INFORMATION_SCHEMA.SYSTEM_USERS”

Using Oracle

1. Create an Oracle database user for the Metrics Service. It is recommended that there be a dedicated user for the Metrics Service to avoid database object name collisions. The Metrics Service team recommends using UTF-8 encoding.

2. Due to licensing issues, the Metrics Service does not provide a JDBC driver for Oracle. Obtain the appropriate JDBC driver and place it into the Web server’s classpath. For example, if running Tomcat, the driver can be placed in the \apache-tomcat-7.0.21\lib directory.

3. Open the \apache-tomcat-7.0.21\lib\MetricsConfig.groovy file and modify the environments → production → dataSource section using the values that are appropriate for the Metrics Service environment. For example:

    dataSource {
        pooled = true
        dbCreate = "none"
        username = "Metrics_user"
        password = "Metrics_password"
        dialect = "org.hibernate.dialect.Oracle10gDialect"
        driverClassName = "oracle.jdbc.driver.OracleDriver"
        url = "jdbc:oracle:thin:@myhost.somewhere.org:1521:DEVDB1"
        properties {
            minEvictableIdleTimeMillis = 180000
            timeBetweenEvictionRunsMillis = 180000
            numTestsPerEvictionRun = 3
            testOnBorrow = true
            testWhileIdle = true
            testOnReturn = true
            validationQuery = "SELECT 1 FROM DUAL"
        }
    }
   

In the example above, an Oracle database user named metrics_user with a password of metrics_password is used for a database named DEVDB1.

There are several different types of Oracle drivers (thin, OCI, kprb) and connection options (service, SID, TNSName) available. Please consult the Oracle DBA and Oracle’s JDBC documentation to create the connection most appropriate for the installed environment.

1. To create the schema, run the \dbscripts\OraclePrefsInitialCreate.sql script prior to starting the Metrics Service.
2. Ensure that the transaction is committed.

Using MySQL

1. Create a schema within MySQL for use with the Metrics Service. It is recommended that there be a dedicated schema for the Metrics Service to avoid database object name collisions. The OWF team recommends using UTF-8 encoding.

2. Create a MySQL user with full access to the schema created above.

3. Due to licensing issues, the Metrics Service does not provide a JDBC driver for MySQL. Obtain the appropriate JDBC driver and place it into the Web server’s classpath. For example, if running Tomcat, the driver can be placed in the \apache-tomcat-7.0.21\lib directory.

4. Open the \apache-tomcat-7.0.21\lib\MetricsConfig.groovy file and modify the environments → production → dataSource section using the values that are appropriate for the Metrics Service environment. For example:

    dataSource {
        pooled = true
        dbCreate = "none"
        driverClassName = "com.mysql.jdbc.Driver"
        url="jdbc:mysql://myhost.somewhere.org/Metrics"
        username = "Metrics_user"
        password = "Metrics_password"
        dialect = "org.hibernate.dialect.MySQL5InnoDBDialect"
        properties {
            minEvictableIdleTimeMillis = 180000
            timeBetweenEvictionRunsMillis = 180000
            numTestsPerEvictionRun = 3
            testOnBorrow = true
            testWhileIdle = true
            testOnReturn = true
            validationQuery = "SELECT 1"
        }
       }
   

In the example above, a MySQL database user named Metrics_user with a password of Metrics_password is used, for a database named Metrics. The dialect org.hibernate.dialect.MySQL5InnoDBDialect will use the InnoDB engine which is recommended for interactive webapps and explicitly used as the engine on the database scripts.

5. Create the schema by running the \dbscript\MySqlPrefsInitialCreate.sql script prior to starting the Metrics Service.

Note: When creating database objects, modify the .sql script (mentioned above) with the appropriate schema name. For example:

   use Metrics;

Using PostgreSQL

1. Create either a new login role or a new schema in order to avoid database object name collisions between the Metrics Service and other database applications.

2. Edit the user so that it can create database objects.

3. Create a new database. Use UTF-8 as encoding (default).

4. Due to licensing issues, the Metrics Service does not provide a JDBC driver for PostgreSQL. Obtain the appropriate JDBC driver and place it into the Web server’s classpath. For example, if running Tomcat, the driver can be placed in the \apache-tomcat-7.0.21\lib directory.

5. Open the \apache-tomcat-7.0.21\lib\MetricsConfig.groovy file and modify the environments → production → dataSource section using the values that are appropriate for the Metrics Service environment. For example:

    dataSource {
        pooled = true
        dbCreate = "none"
        username = "Metrics_user"
        password = "Metrics"
        driverClassName = "org.postgresql.Driver"
        url = "jdbc:postgresql://localhost:5432/Metrics"
        dialect="org.hibernate.dialect.PostgreSQLDialect"
        properties {
            minEvictableIdleTimeMillis = 180000
            timeBetweenEvictionRunsMillis = 180000
            numTestsPerEvictionRun = 3
            testOnBorrow = true
            testWhileIdle = true
            testOnReturn = true
            validationQuery = "SELECT 1"
        }
    }
   

In the example above, a PostgreSQL database user named Metrics_user with a password of Metrics is used, for a database named Metrics.

6. Create the schema by running the PostgreSQLPrefsInitialCreate.sql script before starting the Metrics Service.

Using SQL Server

1. Create a new SQL Server database for use with the Metrics Service.

2. Create a SQL Server user with full access to the Metrics Service database created above.

3. Due to licensing issues, the Metrics Service does not provide a JDBC driver for SQL Server. Obtain the appropriate JDBC driver and place it on the Web server’s classpath. For example, if running Tomcat, the driver can be placed in the \apache-tomcat-7.0.21\lib directory.

4. Open the \apache-tomcat-7.0.21\lib\MetricsConfig.groovy file and modify the environments → production → dataSource section using the values that are appropriate for the environment. For example:

    dataSource {
        pooled = true
        dbCreate = "none"
        username = "sa"
        password = "Metrics"
        driverClassName = "net.sourceforge.jtds.jdbc.Driver"
        url = "jdbc:jtds:sqlserver://localhost:1443/Metrics"
        dialect="ozone.owf.hibernate.OWFSQLServerDialect"
        properties {
            minEvictableIdleTimeMillis = 180000
            timeBetweenEvictionRunsMillis = 180000
            numTestsPerEvictionRun = 3
            testOnBorrow = true
            testWhileIdle = true
            testOnReturn = true
            validationQuery = "SELECT 1"
        }
    }
   

In the example above, the SQL Server database user named sa with password of Metrics is used, to access a database named Metrics.

5. Create the schema by running the SQLServerPrefsInitialCreate.sql script prior to starting the Metrics Service.

Security Setup

The Metrics Service provides a modular security approach that is based on Spring Security. All of the provided options supply both a Spring Security configuration file and Java classes that are written to Spring’s security interfaces in order to perform authentication and authorization.

Installing The Security Module

The OWF-security files, provided in the distribution bundle, offer multiple examples of security options. These are intended as examples and should in no way be used in a production environment. The default security implementation provides an X.509 certificate authentication with CAS fallback. When using the default security module in a testing environment, the user must present a valid X.509 certificate, or a valid CAS login, in order to gain access to the Metrics Service. For each available security option, there is a specific .xml file which must be installed.

Operating the Metrics Service From Different Ports

Initial Metrics Service configuration is set up so that Tomcat can be run from a local installation.

Throughout this document, servername:port implies a localhost:8080 or localhost:8443 location. The example below shows how to set up the Metrics Service so that it can be used on 5050/5443 through the default security module.

To enable ports other than 8080/8443 while using Spring Security, the desired ports need to be explicitly edited in the Web server configuration file, \apache-tomcat-7.0.21\conf\server.xml.

Note: In the event that the Metrics Service is running on a server where a port number is already in use, the Metrics Service must run from a different port number. Two applications cannot bind to the same port.

1. For example, in Tomcat, change the port numbers in \apache-tomcat-7.0.21\conf\server.xml (lines 2, 4 and 6 in the codeblock below):

    1 …
    2 <Connector port="5050" protocol="HTTP/1.1" 
    3                connectionTimeout="20000" 
    4                redirectPort="5443" />
    5 …
    6 <Connector port="5443" protocol="HTTP/1.1" SSLEnabled="true"
    7                maxThreads="150" scheme="https" secure="true"
    8                keystoreFile="certs/keystore.jks" keystorePass="changeit"         
    9                clientAuth="false" sslProtocol="TLS" />
    10 …
   

   A. Ports 5050 and 5443 are just examples and can be changed to whatever is needed. If the Metrics Service was running on a server where a port number was already in use, the SHUTDOWN port must also be changed. To do this, change the port number in the Tomcat Web server configuration file \apache-tomcat-7.0.21\conf\server.xml to another port. In the following example the default shutdown port was changed from 8005 to 8006:

    <Server port="8006" shutdown="SHUTDOWN">
   

   B. Ensure that the port value used in the Web server configuration file match the port value used in \apache-tomcat-7.0.21\lib OzoneConfig.properties, which is shown below, displaying the default port and host information:

    ozone.host = localhost
    ozone.port = 5443
    ozone.unsecurePort = 5050
   

2. Save both files.

3. Restart the Metrics Service server.

Custom Security Logout

The Metrics Service sample security plugins can perform single sign out if the user logged in using CAS authentication. PKI authentication is handled by the browser and requires that the user close the browser to completely sign out. To sign out from LDAP or a custom authentication, the system administrator must implement their own single sign out or instruct the user to close the browser after logout. Use the following lines in the Metrics Security Context file to invoke CAS’s single sign out process.

Security context file:

    <sec:custom-filter ref="casSingleSignOutFilter" after="LOGOUT_FILTER"/>

MetricsCasBeans.xml file:

    <bean id="casSingleSignOutFilter" class="org.jasig.cas.client.session.SingleSignOutFilter"/>
    <bean id="casSingleSignOutHttpSessionListener" class="org.jasig.cas.client.session.SingleSignOutHttpSessionListener" />

Server Certificate Creation and Installation

Valid server certificates are needed for configuring the server to allow HTTPS authentication. Also, the OWF server acts as a client on the Metrics Service. Thus, it must be identified as a user in the authentication files. See the steps below for generating and installing self-signed server certificates.

Generating a New Self-Signed Server Certificate

To generate a new self-signed certificate, the Java keytool utility must be used. This keytool can be used to generate the public/private keys and signed certificates. Using a command window, navigate to the certs directory and execute the following command:

    keytool -genkey -alias servername -keyalg rsa -keystore servername.jks

Note: Some systems do not default to the Java keytool. The keytool can be explicitly called by running the command directly from the JRE/bin directory.

The keytool genkey command will prompt a series of questions. The questions are listed below with example entries matching a server with the name www.exampleserver.org and a keystore password of changeit.

Enter keystore password: changeit
What is your first and last name? [Unknown]: www.exampleserver.org

Note: Make sure to enter the FULLY QUALIFIED server name. This needs to match the hostname of the machine exactly or the certificate will not work correctly.

What is the name of your organizational unit? [Unknown]: sample organization unit
What is the name of your organization? [Unknown]: sample organization
What is the name of your City or Locality? [Unknown]: sample city
What is the name of your State or Province? [Unknown]: sample state
What is the two-letter country code for this unit? [Unknown]: US
Is CN= www.exampleserver.org, OU= sample organization unit, O=sample organization, L= sample city, ST= sample state, C=US correct? [no]: yes

Note: When using an IP address as the Common Name (CN), an entry must be added to the Subject Alternative Name entry in the certificate. The better alternative to using an IP address is to add a name/IP pair to the hosts file and register the name as the CN.

The signed certificate must then be imported into a file to add to the JVM truststore (cacerts):

    keytool -export -file servername.crt -keystore servername.jks -alias servername

Configuring For a Different Truststore/Keystore

For server-to-server calls (Metrics-to-CAS communications, for example) the newly created self-signed certificate should be imported into the truststore.

1. Export the certificate from the keystore into a file:

    keytool -export -file servername.crt -keystore servername.jks -alias servername
   

2. Import the file into the truststore:

    keytool -import -alias servername –keystore mytruststore.jks -file servername.crt
   

Modify the JVM Parameters that are used to start the web-application server in order to utilize the truststore referenced in step 2, shown above. If a Tomcat server is being used, the parameters can be found in the setenv.bat and setenv.sh scripts found within the \apache-tomcat-7.0.21\bin folder inside of the unpacked Metrics-bundle-7-GA.zip.

If an application server other than Tomcat is being used, the parameters will need to be added to the JVM parameters which are loaded when the application server is started.

Table: Custom JVM Parameters

Parameter
`-Djava.awt.headless=true`	Only needed for Unix/Linux deployments
`D-javax.net.ssl.trustStore= "%CATALINA_HOME%\certs\keystore.jks"`	Replace `certs/keystore.jks` with the path and filename to the truststore
-Djavax.net.ssl.keyStorePassword= changeit -server -Xmx1024m -Xms512m -XX:PermSize=128m -XX:MaxPermSize=256m	Replace `changeit` with the truststore’s password (if applicable) and modify memory as needed.

3. Finally, the server configuration must be modified to utilize the new keystore\truststore in SSL (lines 7 and 9 in the codeblock below). Below is the relevant section from the Tomcat configuration script found in \apache-tomcat-7.0.21\conf\server.xml:

    1 <Connector port="8443"
    2 protocol="HTTP/1.1"
    3 SSLEnabled="true"
    4 maxThreads="150"
    5 scheme="https"
    6 secure="true"
    7 keystoreFile="certs/keystore.jks" 
    8 keystorePass="changeit"
    9 clientAuth="false"
    10 sslProtocol="TLS" />
   

Configuring OWF Certificate to Authenticate against Metrics

When using certificate authentication, the Metrics Service must identify the OWF server as an authorized user. To do this:

1. Generate a new self-sign certificate as described in the Generating a New Self-Signed Server Certificate section.
2. Add the server name to the authentication scheme including the user.properties file or any other authentication files such as LDAP.

Note: The server name must have the “user” role associated with it.