Runtime Installation and Configuration Guide

Pre-requisites for Installation

In order to execute Stambia Runtime, your system must meet the following requirements:

Operating System:
- The Runtime can be installed on any system having a Java Virtual Machine (JVM)

Memory / CPU
- The memory and CPU capacity required will depend on the flows that are executed

Disk Space
- The system must have at least 80 MO of free disk space

Java Virtual Machine
- JVM version 1.6 or higher

Note: On a 64-bits system you should use a 64-bits JVM for better performance and compatibility.
Runtime versions prior to S17.1.17 used to require a JDK (Java Development Kit) for publishing Web Services.
For higher versions, a JVM is suffisant.

Warning: Careful, because of identified bugs, version 1.6.0.27 of the Java environment is forbidden.

Stambia Runtime Installation

Installing the Runtime on a Linux/Unix environment

Preliminary steps

1. Install a Java Virtual Machine (JVM) 1.6 or higher
2. Set the environment variable STAMBIA_JAVA_HOME to the folder situated located just before the “bin” folder in your JDK

Runtime Installation

1. Unzip the archive which has been downloaded into the target folder
2. Set the execution permissions on the SH files at the root (if needed)
3. Set the write permissions, especially on the directories: ‘temp, ‘build’ and ‘sessions’
4. Modify the engineParameters.xml file, as explained below.
5. If needed create the file engineScheduler.properties, as explained below
6. If necessary, put the ‘sh’ in the starting processes of the Linux server (this procedure depends on the system)

Some environment variables may be modified:

• STAMBIA_JAVA_HOME : path of the JVM that is used
• STAMBIA_PROPERTIES_LOCATION: path of the ‘properties’ folder
• STAMBIA_INIT_MEMORY: Runtime’s JVM initialization memory
• STAMBIA_MAX_MEMORY: Runtime’s JVM maximum memory
• STAMBIA_STACK_SIZE: Runtime’s JVM stack size

Note: In order to ease updates, it is recommended to copy the Stambia ‘properties’ folder into another place and to set the parameters of the STAMBIA_PROPERTIES_LOCATION variable so that it points to it. In this way, Runtime updates can be made by replacing the whole arborescence. The configuration data of the ‘properties’ folder will not be lost, since it will be elsewhere.

Installing the Runtime on a Windows environment

Please refer to Linux/Unix installation, except for points 2 and 6 that are not useful in Windows.

Service installation

The runtime can be easily installed as a Windows service if needed.
For this, navigate to the root directory of the Runtime and use the following commands:

1. use the installEngineAsService.bat -i [<serviceName>] command to install the service
2. use the installEngineAsService.bat -r [<serviceName>] command to remove the service

The <serviceName> parameter can be useful to install multiple Runtimes on the same machine.
If not set the service will be named ‹Stambia Runtime›.

The file «stambiaEngine.conf» which is in the folder external\stambiaService\conf can be used to configure some of the service’s properties. By default, it is not useful to modify this file.

Warning: Any modification of Stambia Runtime files or parameters (in “properties” or in the ‘.bat’ files) requires the removal and reinstallation of the Windows service, so that these modifications may be taken into account.

Tip: The specified user used to launch the Runtime (Windows service) should be changed to a user with network abilities, usually a domain user.

Upgrading in a few steps

After downloading the desired Runtime ZIP archive, proceed through the steps listed below.

We assume your current Runtime is installed into a directory named «stambiaRuntime».

1. Install the new Runtime in a new directory, something like "stambiaRuntime_new"
2. On UNIX/Linux systems make sure that all the stambiaRuntime_new/*.sh files are executable
3. Stop the old Runtime and make a backup
4. Copy the content of the following directories from the old Runtime to the new Runtime:
   1. stambiaRuntime\build\deliveries
   2. stambiaRuntime\build\packages
   3. stambiaRuntime\lib\addons (if you have additional libraries added to the Runtime)
   4. stambiaRuntime\properties (if you have set some properties)
   5. stambiaRuntime\scheduler (if you are using the Runtime’s scheduler)
   6. stambiaRuntime\sessions (if you use the Runtime’s internal log database)
   7. Optionally: stambiaRuntime\temp (if your Processes store specific files intentionnally in this directory)
5. Install the required Jdbc jar files into stambiaRuntime_new/lib/jdbc (do not overwrite the new Runtime’s Jdbc jar files!)
6. Rename the old Runtime’s directory to something like "stambiaRuntime_old"
7. Rename the new Runtime’s directory to "stambiaRuntime"
8. Apply the read / right permissions to the new folder as it was set on the old one
9. If the Runtime is installed as a Windows service, remove and re-install the service
10. Start the Runtime

Runtime Configuration

Most of the Runtime’s configuration is done in the properties/engineParameters.xml file

This file allows to manage:

• The engine parameters (such as started services, listening ports, ...)
• The security of the Runtime (hostname and user / password restriction, roles)
• The repositories where the deliveries are stored
• The Java additional options to add at Runtime’s startup
• The log database configuration

Defining the started services

The services exposed by the Runtime, such as the scheduler, the SOAP component, or the internal Java database can be turned off if needed.
By default, they are all launched at the Runtime’s startup.
To specify which services should be started:

1. Open the engineParameters.xml file
2. Update the parameters accordingly to your needs.

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="launchSchedulerEngine" value="true"/>
		<parameter name="launchExecutionEngine" value="true"/>
		<parameter name="launchReportEngine" value="true"/>
		<parameter name="startInternalDb" value="true"/>
		<parameter name="startSoapServer" value="true"/>
		<...>
	</engineParameters>
	<...>
</parameters>

The following parameters are available:

Defining the services ports

The services exposed by the Runtime are running on defined port, that can indeed be modified easily.

1. Open the engineParameters.xml file
2. Update the following parameters accordingly to your needs.

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="rmiPort" value="42000"/>
		<!--<parameter name="rmiCallbackPort" value="42000"/>-->
		<parameter name="internalDbTcpPort" value="42100"/>
		<parameter name="internalDbWebPort" value="42101"/>
		<parameter name="soapServerPort" value="42200"/>
		<...>
	</engineParameters>
	<...>
</parameters>

Defining the log database

The Runtime stores the information about sessions' execution in a log database.
This database is by default an internal H2 database, that is shipped with the Runtime and started with it.

This offers a ready-to-go environment that can be used immediately.
We however recommend changing it to a more robust database such as Oracle, Microsoft SQL Server (MSSQL), etc for production use.
You will need to provide to Stambia Runtime a user having read and write permissions on the chosen database/schema.

Here is how to change the log database of the Runtime:

1) Open the engineParameters.xml file
The configuration is performed in this file, which contains samples for the most known databases.

2) Modify the log database parameters as explained below.
This consists of defining the JDBC URL, user, password, schema, ... where the log database will be located.

3) Restart the runtime
All necessary tables will be created automatically the first time the log database is initialized

Log database parameters

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="userLogDefaultName" value="logDatabase"/>
		<parameter name="defaultSessionLogLevel" value="400"/>
		<...>
	</engineParameters>
	<...>
	<logs>
		<...>
		<log userLogName="logDatabase" autoUpdate="true" userLogClass="com.indy.engine.userLog.RdbmsUserLog">
			<parameter name="userLogRdbmsDriver" value="org.h2.Driver"/>
			<parameter name="userLogRdbmsUrl" value="jdbc:h2:tcp://localhost:42100/sessions/internalDb/sessionLogs"/>
			<parameter name="userLogRdbmsUser" value="sa"/>
			<parameter name="userLogRdbmsPassword" value=""/>
			<!--<parameter name="userLogRdbmsEncryptedPassword" value=""/>-->
			<parameter name="userLogRdbmsVarcharType" value="varchar"/>
			<parameter name="userLogRdbmsVarcharMaxSize" value="1000"/>
			<parameter name="userLogRdbmsNumericType" value="numeric"/>
			<parameter name="userLogRdbmsClobType" value="clob"/>
			<parameter name="userLogRdbmsBlobType" value="blob"/>
			<parameter name="userLogRdbmsSchemaName" value="logs"/>
			<parameter name="userLogRdbmsUseSchemaNameForIndexCreation" value="true"/>
			<parameter name="userLogRdbmsDeleteSyntaxe" value="Delete from"/>
			<!--<parameter name="userLogRdbmsTablePrefix" value="STB_LOG_"/>-->
			<!-- bestCompression / bestSpeed / default-->
			<parameter name="userLogRdbmsCompressedLevel" value="bestCompression"/>
			<!-- text / binary / compressed-->
			<parameter name="userLogRdbmsDeliveryFormat" value="compressed"/>
			<parameter name="userLogRdbmsPropertyMaxVarcharSize" value="1000"/>
			<!-- -1 : infinite -->
			<parameter name="userLogRdbmsPropertyMaxClobSize" value="10000"/>
			<!-- binary / compressed-->
			<parameter name="userLogRdbmsPropertyBinaryFormat" value="compressed"/>
			<parameter name="userLogRdbmsTimestampQuery" value="select now()"/>
			<parameter name="userLogRdbmsInactivityDetectionPeriod" value="90000"/>
			<parameter name="userLogRdbmsActivityRefreshInterval" value="60000"/>
			<parameter name="userLogRdbmsDeletionWithNotExists" value="true"/>
			<!--<parameter name="userLogRdbmsIndexCreationOption" value=""/>-->
			<!--<parameter name="userLogRdbmsTableCreationOption" value=""/>-->
		</log>
		<...>
	</logs>
	<...>
</parameters>

User Log Default Name

The «userLogDefaultName» is used to define which configured log database should be used.
This corresponds to the «userLogName» attribute which can be found in the log database configuration nodes(<log></log> nodes)

Default Session Log Level

The «defaultSessionLogLevel» defines what level of information is logged inside log database for each session executed by the Runtime.
The higher the value is the higher information are logged.
Possible values are the following: -1, 0, 100, 200, 300, 400

Note that is applies only for sessions on which the log level is not defined manually at execution.
Refer to the runtime parameters reference part of this documentation for details information about each value.

Log part

This is the part where you will configure the JDBC URL, user, password, schema, ... to connect to the log database.
All necessary tables will be created automatically the first time the log database is initialized.
The initialization is performed the first time the Runtime is started on this log database.

Under <logs></logs> node, you can find commented examples of configuration for several databases systems.
You can use these examples to configure your log database accordingly to the target database system which will be used.

The Runtime will use as log database the <log></log> node which «userLogName» attribute value corresponds to the «userLogDefaultName» parameter value.

If you uncomment the examples nodes to, you’ll therefore have to be careful to keep only one <log></log> node which «userLogName» attribute value corresponds to the «userLogDefaultName» parameter value.

Example

The example below is for an Oracle database:

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="userLogDefaultName" value="logDatabase"/>
		<parameter name="defaultSessionLogLevel" value="400"/>
		<...>
	</engineParameters>
	<...>
	<logs>
		<...>
		<log userLogName="logDatabase" autoUpdate="true" userLogClass="com.indy.engine.userLog.RdbmsUserLog">
			<parameter name="userLogRdbmsDriver" value="oracle.jdbc.driver.OracleDriver"/>
			<parameter name="userLogRdbmsUrl" value="jdbc:oracle:thin:@[host]:[port]:[sid]"/>
			<parameter name="userLogRdbmsUser" value="[USER]"/>
			<parameter name="userLogRdbmsPassword" value="[PASSWORD]"/>
			<parameter name="userLogRdbmsSchemaName" value="[SCHEMA_NAME]"/>
			<parameter name="userLogRdbmsVarcharType" value="varchar2"/>
			<parameter name="userLogRdbmsVarcharMaxSize" value="4000"/>
			<parameter name="userLogRdbmsClobType" value="clob"/>
			<parameter name="userLogRdbmsBlobType" value="blob"/>
			<parameter name="userLogRdbmsNumericType" value="number"/>
			<parameter name="userLogRdbmsDeleteSyntaxe" value="Delete from"/>
			<parameter name="userLogRdbmsDeliveryFormat" value="text"/>
			<parameter name="userLogRdbmsPropertyMaxVarcharSize" value="1000"/>
			<parameter name="userLogRdbmsPropertyMaxClobSize" value="10000"/>
			<parameter name="userLogRdbmsPropertyBinaryFormat" value="compressed"/>
		</log>
		<...>
	</logs>
	<...>
</parameters>

The minimum to modify are the following parameters:

• userLogRdbmsUrl
• userLogRdbmsUser
• userLogRdbmsPassword
• userLogSchemaName

Note: Refer to the ‹Runtime parameter reference› part of this documentation for the list of all available parameters with explanations.

Defining Repositories

Repositories are the locations where the Runtime will look for the delivery files at execution.

There are two types of repositories:

• File Repositories: a location where .deliv files are stored on the filesystem.
• Http Repositories: permit to retrieve deliveries through HTTP protocol. The Runtime will connect to Stambia Analytics Deployment Managers in order to retrieve deliveries that are marked as Remotely Available.

To add, configure, and specify repositories:

1. Open the engineParameters.xml file
2. Configure the repositories

Example of repositories configuration:

<parameters>
	<...>
	<repositories>
		<fileRepository name="default" default="true" folder="build/deliveries/"/> 
		<fileRepository name="webService" default="true" folder="build/deliveries/wsdl/" webService="true" synchPollingInterval="10000" scanMode="polling"/>
		<httpRepository name="PROD" default="false" url="http://localhost:8080/analytics" user="stambia" uncryptedPassword="stambia" unreachableTolerancePeriod="30000"/>
	</repositories>
	<...>
</parameters>

Important: It is possible to specify multiple repositories on a same Runtime, but note that you can only set one as default for standard deliveries, and one as default for web service deliveries.

Tip: You can specify the repository name at execution time:
startdelivery.bat -name myDeliv -repository demo

File Repositories

scan Modes

1. polling: The Runtime will check periodically if new deliveries are available in the repository. This is useful only for deliveries exposed as web service. To define the polling interval, please see the synchPollingInterval parameter.
2. disable: The Runtime will not check for new deliveries in the repository. This means that the runtime must be restarted to take into account the web service deliveries that are manually added or modified in the repository. This do not apply for deliveries published from a Designer, that are automatically exposed.

Examples:

<parameters>
	<...>
	<repositories>
		<fileRepository name="defaultRepository" default="true" folder="build/deliveries"/> 
		<fileRepository name="wsdlRepository" default="true" folder="build/deliveries/wsdl/" webService="true" synchPollingInterval="10000" scanmode="polling">
		<...>
	</repositories>
	<...>
</parameters>

Http Repositories

scan Modes

1. polling: The Runtime will check periodically if new deliveries are available in the repository. This is useful only for deliveries exposed as web service. To define the polling interval, please see the synchPollingInterval parameter.
2. disable: The Runtime will not check for new deliveries in the repository. This means that the runtime must be restarted to take into account the web service deliveries that are manually added or modified in the repository. This do not apply for deliveries published from a Designer, that are automatically exposed.

Note: Passwords are encrypted using the encrypt <password> command on the Runtime engine console (engine command line tool).

Example:

<parameters>
	<...>
	<repositories>
		<httpRepository name="PROD" default="false" url="http://localhost:8080/analytics" user="stambia" uncryptedPassword="stambia" unreachableTolerancePeriod="30000"/>
		<...>
	</repositories>
	<...>
</parameters>

Defining Java Additional Options

Java options are generally added to the Java command launching the Runtime with the -DmyOption01=value01 argument.
This part allows to set them directly in the Runtime’s Configuration file through the javaConfiguration node.
The options specified inside will be loaded just after the Runtime’s start.

1. Open the engineParameters.xml file
2. Set the additional options you want to add at Runtime’s startup.

The syntax is the following:

<parameters>
	<...>
	<javaConfiguration>
		<property name="myOption01" value="value01"/>
		<property name="myOption02" value="value02"/>
		<...>
	</javaConfiguration>
	<...>
</parameters>

Securing the Runtime

A Runtime installed with the default configuration can be accessed by anyone.

Any user can connect and make operations on it, such as listing or executing sessions.

This behavior can be configured easily in the Runtime Properties (engineParmeters.xml) , that offer the possibility to secure the connection through

• TLS secured RMI
• User / Password system with roles (permissions)
• Hostname / IP restriction
• HTTPS for Web Service Endpoints

A basic security configuration looks like this:

For TLS secured RMI:

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="rmiEnableTls" value="true"/>
		<...>
	</engineParameters>
	<...>
</parameters>

For user / hostname restriction:

<parameters>
	<...> 
	<security>
		<user anonymous="true" roles="Connect View"/>
		<user name="admin"  uncryptedPassword="admin" roles="Admin"/>
		<user name="developer"  uncryptedPassword="developer" roles="Connect View Execute"/>
		<user name="consult"  uncryptedPassword="consult" roles="Connect View"/>
		<allow address="192.168.0.42"/>
	</security>
	<...>
</parameters>

Warning: The security node must contain at least one user, which can be a normal or anonymous user.

For HTTPS Web Services:

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="webServiceSecureProtocol" value="TLSv1.1"/>
		<parameter name="webServiceKeyStoreFile" value="D:/keystore/mykeystore.jks"/>
		<parameter name="webServiceKeyStoreType" value="JKS"/> 
		<parameter name="webServiceKeyStorePassword" value="password"/> 
		<parameter name="webServiceKeyPassword" value="password"/>
		<...>
	</engineParameters>
	<...>
</parameters>

TLS enabled RMI

Set the following parameter to true if you the RMI connection to be secured through TLS.
The RMI connection is used for instance to connect to the Runtime from the Designer or Analytics.

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="rmiEnableTls" value="true"/>
		<...>
	</engineParameters>
	<...>
</parameters>

User / Password Restriction and Roles

You can define the users that can connect to the Runtime and their permissions.

The syntax is the following:

<parameters>
	<...> 
	<security>
		<...>
		<user anonymous="true" roles="Connect View"/>
		<user name="user01"  password="encrypted password" uncryptedPassword="plain text password" roles="Connect View Execute"/>
		<user name="user02"  password="encrypted password" uncryptedPassword="plain text password" roles="Connect View Execute"/>
		<...>
	</security>
	<...>
</parameters>

The following parameters are available:

The following roles are available:

About the Anonymous User:

An anonymous user can be set, to specify the permissions of the users that connect to the Runtime without specifying credentials.

<user anonymous="true" roles="Connect View"/>

When the anonymous user is set, it is therefore not mandatory to specify credentials when connecting.
The connected user will have the permissions of the anonymous user.

When the anonymous user is not set, specifying credentials when connecting is mandatory.
Anonymous connections will then be rejected.

Note that only one anonymous user can be set at a time.

Notes:
* Passwords are encrypted using the encrypt <password> command on the Runtime engine console (engine command line tool).
* Only one of the password or uncryptedPassword should be set
* Multiple roles can be assigned to one user, separated with space characters

Warning: The security node must contain at least one user, which can be a normal or anonymous user.

Hostname / IP restriction

You can define the hostnames / IP addresses that are allowed to connect to the runtime.

The syntax is the following:

<parameters>
	<...> 
	<security>
		<...>
		<allow address="Hostname or IP Address"/>
		<allow address="Another Hostname or another IP Address"/>
		<...>
	</security>
	<...>
</parameters>

Warning: The security node must also contain at least one user, which can be a normal or anonymous user.

Enabling HTTPS on Web Services Endpoints

Deliveries published as Web Service can be accessed through the different Web Services Endpoints exposed by the Runtime.
These endpoints can be accessed by default through HTTP using the URLs indicated on the console at Runtime’s startup.
This default behavior can be modified easily in the Runtime configuration file to enable the use of HTTPS, as explained below.

The following parameters are available to enable HTTPS:

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="webServiceSecureProtocol" value="TLSv1.1"/>
		<parameter name="webServiceKeyStoreFile" value="D:/keystore/mykeystore.jks"/>
		<parameter name="webServiceKeyStoreType" value="JKS"/> 
		<parameter name="webServiceKeyStorePassword" value="password"/> 
		<parameter name="webServiceKeyPassword" value="password"/>
		<...>
	</engineParameters>
	<...>
</parameters>

And here is their description:

Configuring the scheduler

The scheduler shipped with the Runtime stores all the schedules into a database.
This database is by default an internal H2 database, that is shipped with the Runtime and started with it.

If you want to change this and store the schedules into another database:

• Create the necessary tables in the target database using the scripts that are in stambiaRuntime/scripts/scheduler
• Copy the stambiaRuntime/properties/samples/schedules/engineScheduler.properties into stambiaRuntime/properties
• Open it and configure it as explained below

When the property org.quartz.jobStore.dataSource is set to internal (which is the default), the scheduler stores its schedules in the internal database.
Therefore, change it to another name when you want to use another database.

Finally, define the datasource parameters to match the location where the tables are created.

org.quartz.jobStore.class=org.quartz.impl.jdbcjobstore.JobStoreTX
org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.StdJDBCDelegate 
org.quartz.jobStore.useProperties=false
#org.quartz.jobStore.dataSource=internal
org.quartz.jobStore.dataSource=database01
org.quartz.jobStore.tablePrefix=STB_
org.quartz.jobStore.isClustered=false
#============================================================================
# Configure Datasources  
#============================================================================
org.quartz.dataSource.database01.driver =org.h2.Driver
org.quartz.dataSource.database01.URL = jdbc:h2:tcp://localhost:42100/scheduler/internalDb;SCHEMA=SCHEDULER
org.quartz.dataSource.database01.user = sa
org.quartz.dataSource.database01.password = 
org.quartz.dataSource.database01.maxConnections = 5
org.quartz.dataSource.database01.validationQuery=

Starting a Runtime with a configuration file

A Runtime may be started with a specific configuration file.
To specify this file, use the environment variable STAMBIA_CONF_FILE_LOCATION

By default, the value configured in the file «initvariable.sh (.bat)» is this:

STAMBIA_CONF_FILE_LOCATION=$STAMBIA_PROPERTIES_LOCATION/engineParameters.xml

Automatic log purge

You can plan an automatic purge of the Runtime session logs.
This can be done in Stambia and Stambia Analytics in the Purge tab of the Runtime Editor or alternatively on command line as explained below.

To proceed:

1. Launch startCommand (.bat or .sh).
2. Then use the purge scheduling command, the description of which follows:

schedule purge keep <number> <minute|hour|day|session>  cron <cronExpression> [sessionname <name,name2,...>] [status <done,error,killed>] [on host <hostname>] [port <hostport>]

It is possible to purge while keeping:

• A number of days, hours or minutes
• A number of sessions

For example, to keep 90 days and schedule the purge every evening at 23h:

schedule purge keep 90 day cron "0 0 23 * * ?"

Runtime parameters reference

The configuration of the Runtime is done in the engineParameters.xml file that can be found in the properties folder of the Runtime’s installation.
This file allows to manage:

• The engine parameters (such as started services, listening ports, ...)
• The security of the Runtime (hostname and user / password restriction, roles)
• The repositories where the deliveries are stored
• The Java additional options to add at Runtime’s startup
• The log database configuration

Take care, it is highly recommended to check first with Stambia the modifications you wish to bring to the XML files containing the Runtime parameters.
You can moreover find configuration samples in the properties/samples folder.

Note: Passwords are encrypted using the encrypt <password> command on the Runtime engine console (engine command line tool).

Tip: All the parameters are centralized in this file but can be easily externalized if required.

Engine Parameters

Common Parameters

Services Parameters

Services Ports Parameters

Services Security

Services Miscellaneous Parameters

Standard Output Parameters

Web Services Parameters

Logs parameters

In this part, the default values will be those used for the logs in H2 (the internal base). For other logs examples, please refer to the example files that are provided.

Log header

Internal parameters

Note: Passwords are encrypted using the encrypt <password> command on the Runtime engine console (engine command line tool).

Session Log Level

The session log level defines the level of information which is logged inside log database for each session executed by the Runtime.

The higher the value is the higher information are logged.
You can find below the different log level values and what level of details can be consulted, depending on the session status.