Hyades Data Collection Engine Configuration Readme

Contents

• Introduction
• Base Configuration
• Plugin Configuration
• Elements and Attributes
• Known Issues

Introduction

The Hyades Data Collection Engine configuration is specified by two sets of configuration files. The first set is the base configuration which describes the default settings of the engine. The second set is the plugin configuration which describes the application-specific settings of the engine. This document describes the detail of each configuration and how to write configuration extensions.

The directory “<install directory>” referred in this document corresponds to the path where the Hyades Data Collection Engine is unpacked. This directory is also referred as “%RASERVER_HOME%” in the configuration files.

Base Configuration

The base configuration consist of the file “<install directory>/config/serviceconfig.xml” which is constructed using the XML schema “<install directory>/config/serviceconfig.xsd”. This specifies the default settings such as system environment variables, application configurations and connectivity of the Hyades Data Collection Engine. The base configuration will be availabe to all configurations and is loaded when the engine service is started. Application developers should not modify this base configuration file since any changes in the base configuration will be global. Plugin configurations (described below) should be used to specify plugin and application specific settings.

Plugin Configuration

Each user-defined application should have its configuration file and dependencies being placed under the plugin directory “<install directory>/plugin/<plugin name>” where “<plugin name>” is a unique name which identifies the application. The plugin configuration file “pluginconfig.xml” should be placed under the “config” subdirectory of the plugin directory. Typically, JAR files are placed under the “lib” subdirectory of the plugin directory. Developers can use the XML schema “<install directory>/config/pluginconfig.xsd” to help constructing the plugin configuration file.

Elements and Attributes

Element: AgentControllerConfiguration

This is the root element of the base configuration. The settings are used for starting the engine service.

Used by: Base Configuration

Sub-elements: AgentControllerEnvironment, Application, Hosts, Service, Agent, Option, Plugin

Attributes:

• activeConfiguration - specify which configuration is to be loaded at engine startup
• jvm - fully qualified path of the Java Virtual Machine dynamic runtime library (jvm.dll or libjvm.so)
• loggingDetail - enable line number logging of the engine if HIGH is specified
• loggingDirectory - directory where the engine log file “servicelog.log” is created
• loggingLevel - severity filter for log messages
• port - engine port for listening to incomming unsecured client connection
• securedPort - engine port for listening to incomming secured client connection
• version - version of the engine

Element: PluginConfiguration

This is the root element of the plugin configuration. The settings are loaded after the base configuration is loaded.

Used by: Plugin Configuration

Sub-elements: AgentControllerEnvironment, Application, Service, Agent, Option

Attributes:

• requires - a comma-separated list of plugin name(s) which this configuration is depending on

Element: AgentControllerEnvironment

This is a place holder for global environment variable(s) contributed by this configuration. These are published to the system and available to all other configurations including the base configuration.

Used by: AgentControllerConfiguration, PluginConfiguration

Sub-elements: Variable

Attributes:

• configuration - name of the configuration where the environment variables are to be added

Element: Application

This is a place holder for application specific environment. The settings within are only visible to this particular application.

Used by: AgentControllerConfiguration, PluginConfiguration

Sub-elements: Variable, Parameter

Attributes:

• configuration - name of the configuration where the application is to be added
• executable - name of the application, clients must use this name to identify this application
• path - the actual, fully qualified path of the program which this application should run
• location - working directory of this application
• extends - the configuration name which the same application is already defined, this will add the current settings on top

Element: Hosts

This is a place holder for host information. This is used by the engine to allow / disallow certain host(s) to connect.

Used by: AgentControllerConfiguration

Sub-elements: Allow, Deny

Attributes:

• configuration - name of the configuration which this host information is used

Element: Allow

This specifys which host(s) are allowed to connect to the engine.

Used by: Hosts

Attributes:

• host - name or IP address of the host
• net - subnet
• mask - subnet mask

Element: Deny

This specifys which host(s) are disallowed to connect to the engine.

Used by: Hosts

Attributes:

• host - name or IP address of the host
• net - subnet
• mask - subnet mask

Element: Service

This specify which user defined module to load at engine startup.

Used by: AgentControllerConfiguration, PluginConfiguration

Sub-elements: Option

Attributes:

• configuration - name of the configuration which this service is to be loaded
• name - name of the service
• path - the fully qualified path of the dynamic loading library

Element: Agent

This specify agent specific information.

Used by: AgentControllerConfiguration, PluginConfiguration

Sub-elements: Option

Attributes:

• configuration - name of the configuration which this agent configuration is used
• name - name of the agent
• type - type of the agent
• dataChannelSize - amount of shared memory to allocate for interprocess communication
• logFile - fully qualified path for the log file which writes the messages sent by the agent
• client - specify whether this agent is dynamic or headless

Element: Option

This is used to store a name-value pair.

Used by: AgentControllerConfiguration, PluginConfiguration, Service, Agent

Attributes:

• name - name of the option (i.e. namespace)
• type - type of the option (i.e. option name)
• value - value of the option

Element: Plugin

This specify the directory to look for plugin configurations

Used by: AgentControllerConfiguration

Attributes:

• path - fully qualified directory to look for plugin configurations

Element: Variable

Environment variable.

Used by: Application, AgentControllerEnvironment

Attributes:

• name - name of the environment variable (e.g. CLASSPATH)
• value - value of the environment variable
• position - specify whether this value is to be appended, prepended, or replacing the existing value

Element: Parameter

Program parameter.

Used by: Application

Attributes:

• value - value of the program parameter
• position - specifying whether this parameter is to be appended, prepended, or replacing the existing parameter

Known Issues

1. Application cannot overwrite an already-loaded application with the same name and configuration. It can only extend the application by specifying the “extends” attributes in its configuraiton.
2. Configurations are loaded alphabetically unless the configuration is dependent on other configurations, which in that case the dependent configurations will be loaded first. If any of the depencencies fails to load, the configuration will not be loaded at all.