Simulation CLI Deployment

Tags: not added yet

Simulation Deployment

This document describes the process of deploying a simulation developed with the Object Modeling System for the purpose of using it outside of the OMS IDE.

Use cases:

hand over a simulation to a user who just wants to apply the model
a model will be used in a deployment environment such as a web server, etc.
a simulation should be certified for production by an authorized person or institution, the simulation can be explored since it is self-documenting with respect to its components, model, and parameter files.

A simulation is deployed as a Jar file. This is called a Simulation Jar. This simulation jar has the following characteristics

It contains all the resources that are required by that simulation such as the simulation file, the model, the components, default parameter sets, libraries.
It also contains all the OMS runtime classes to execute the simulation.
It contains description about the origin and version of those resources.

The simulation jar is self contained, no other external classes are required to run the simulation, everything needed is packaged together. The simulation jar is also 'sealed'. Only classes from within the simulation file are being used for execution, no external code cannot be injected into the simulation. This is an important security feature.

Deploying a Simulation as Jar

To deploy a simulation, right click in OMS on the *.jsa file and invoke Build CLI. That is all it takes to create the Simulation Jar. If the simulation is named EFCarson.jsa the simulation jar will be EFCarson.jar and be stored in the <project>/dist/models folder.

Running a Simulation Jar

Running a simulation jar is easy. As a minimal requirement the installation of the JRE version 1.6+ installed. At the command prompt you execute the jar file directly by passing the -jar option to the Java JVM and the name of the simulation jar.

$ java -jar EFcarson.jar

The above command verifies the digital signatures (if present) and executes the simulation with its default settings.

Exploring a deployed simulation

The content of a Simulation Jar can be explored. By passing the ? at the end of the execution command line, all relevant meta data will be printed out.

$ java -jar EFcarson.jar ?

Object Modeling System, CLI Simulation & Runtime
  Usage: java -jar null.jar [options]
    options: -P<param file>  Parameter file(*.csp)
             -O<output dir>  Output directory
             -?              this output

  Built From: C:\od\oms\work21\prms\scenarios\EFCarson.jsa
  Built At  : Wed Oct 22 15:30:03 MDT 2008
  Built By  : od
  Built On  : Windows XP - x86 - 5.1

  Simulation: EFCarson
    Model:            \META-INF\oms\models\prms_radpl.jma
    Parameter Files:  [\META-INF\oms\data\efcarson.csp, 
                       \META-INF\oms\data\efcarson_dates.csp, 
                       \META-INF\oms\data\efcarson_files.csp, 
                       \META-INF\oms\data\efcarson_luca.csp]

Version Information of Simulation Resources

The Simulation Jar's manifest file contains all the resources that belong to this simulation. If there is version information available within the components, the model and the parameter files at the time of Simulation Jar's creation, it will be carried over into the Simulation Jar's manifest file.

Component Versioning

To add version information to a component you need to add the @VersionInfo(...) annotation to the component. This annotation takes a string argument, that somehow describes the version of this component.

Example Using custom version information:

import org.oms.model.data.annotation.*;
...

@VersionInfo("1.0")

public class NewOutput implements Stateful, AttributeLookup {
...

A developer is responsible for providing meaningful version info. This is might be tedious for large projects to manage manually. A version control system can automate here. The example below shows version info using VCS keyword substitution.

import org.oms.model.data.annotation.*;
...

@VersionInfo("$Id: NewOutput.java 58 2008-10-16 17:36:05Z david $
   $HeadURL: https://colab.sc.egov.usda.gov/svn/PRMS/trunk/prms/src/gov/usgs/prms/NewOutput.java $")

public class NewOutput implements Stateful, AttributeLookup {
...

This example uses Subversion keyword substitution to provide more comprehensive version information such as the source file name, the revision number of the latest modification, the time of the commit and the user. It also shows here the head URL of the file, the repository and its location. This example will lead to a manifest entry within the EFCarson.jar file:

Name: gov/usgs/prms/NewOutput.class
OMS-Class: Component
Version: $Id: NewOutput.java 58 2008-10-16 17:36:05Z david $ $HeadURL:
  https://colab.sc.egov.usda.gov/svn/PRMS/trunk/prms/src/gov/usgs/prms
 /NewOutput.java $

The manifest section entry lists the compiled OMS component, and the version attribute as being defined on the component (Example 2). With such information someone should be able at later time to recover and trace back the component source.

Parameter File Versioning

Parameter file versioning is done using supported the meta data

Model Versioning

Within the graphical OMS ModelEditor, each model has a property Version that can be set in the Property window. This information will be put into the Simulation Jar file's manifest.mf file as a section attribute.

Name: META-INF/oms/models/prms_radpl.jma
OMS-Class: Model
Version: 1.0

Any string information can be used here. Note, that you cannot put VCS keywords in here, since the model is stored as a binary format.

Digitally signing a Simulation

Once a Simulation is deployed as a single jar file, it can be digitally sign with an electronic "signature". A digital signature ensures the integrity of the developed simulation. Once signed a simulation jar cannot be altered: Components, default parameter settings, and the Model cannot be switched or patched. The signature protects the investment to develop a complex simulation setup. However you can overwrite public parameter values, an can control output generation.

Creating a self signed certificate

You have to have install the Java SDK from http://java.sun.com/j2se/downloads.html; the tools have to be in your path

Step 1 - Create a key:

keytool -alias keyname -genkey

This will create a new keystore (usually $HOME/.keystore) if not present or add to it.

Step 2 - Sign the jar file using the key - Sign mindterm.jar:

jarsigner mindterm.jar keyname

Importing an issued certificate

You need to import ...

$ keytool -import -alias od  -file OD.cer

Validating the Integrity of a Simulation

Once a Simulation jar is signed it gets verified on execution:

$ java -jar EFCarson.jar

If verification fails, execution will not happen.

You can also verify the Simulation Jar with the jarsigner tool

$ jarsigner -verify  EFCarson.jar
jar verified.

Warning: 
This jar contains entries whose signer certificate will expire within six months. 

Re-run with the -verbose and -certs options for more details.

To get more details on certain component signatures:

$ jarsigner -verbose -certs -verify  EFCarson.jar

...

smk     1536 Thu May 24 10:17:22 MDT 2007  gov/usgs/prms/PrecipKrig.class

      X.509, CN=Olaf David, OU=CSU, O=CSU, L=FC, ST=CO, C=US (od)
      [certificate will expire on 1/14/09 10:44 AM]

smk     1593 Thu May 24 10:17:22 MDT 2007 gov/usgs/prms/Obs.class

      X.509, CN=Olaf David, OU=CSU, O=CSU, L=FC, ST=CO, C=US (od)
      [certificate will expire on 1/14/09 10:44 AM]
...

  s = signature was verified 
  m = entry is listed in manifest
  k = at least one certificate was found in keystore
  i = at least one certificate was found in identity scope

These examples show different levels of protecting a Simulation jar using digital signatures

Conclusion

The CLI Deployment of OMS Simulations is easy to perform and has the following features and benefits.

Simulations can be packaged into an executable simulation jar.
The simulation jar contains all code, data, and resources as defined within the OMS IDE to run the simulation
To run a simulation only a Java Runtime Environment and the Simulation Jar are needed, no OMS installation is required.
Simulation jars are sealed and can be digitally signed. Therefore a deployed simulation jar is secure and cannot be compromised
Simulation jars carry all information about the origin of resources that make up this simulation such as the version of components, data sets and the model. All sources can be traced back, if version info is present.