Agent Controller configuration files

The Agent Controller 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 plug-in 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 Agent Controller 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 Agent Controller. The base configuration will be available 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. Plug-in configurations (described below) should be used to specify plug-in and application specific settings.

Plug-in Configuration

Each user-defined application should have its configuration file and dependencies being placed under the plug-in directory <install directory>/plugin/<plug-in name> where <plug-in name> is a unique name which identifies the application. The plug-in configuration file pluginconfig.xml should be placed under the config subdirectory of the plug-in directory. Typically, JAR files are placed under the lib subdirectory of the plug-in directory. Developers can use the XML schema <install directory>/config/pluginconfig.xsd to help constructing the plug-in 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
filePort
specify the port which the Agent Controller file transfer service is listening to. The default value is 10005.
isDataMultiplexed
specify whether profiling and logging data should be transmitted over the control channel of the Agent Controller. By default, data channel uses an arbitrary port for data transmission and may be blocked by the existence of a firewall. Transferring the data over the control channel will allow a set of predefined ports to be opened for incoming connection requests through a firewall. These ports include the default port 10002, secured port 10003, and the file server port 10005. The default value for this attribute is false.
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 incoming unsecured client connection
processPolling
specify whether or not active checking of process status is enabled. This attribute is primarily used on Windows systems to make sure the Agent Controller is notified whenever a process has terminated. The default value is true.
securedPort
engine port for listening to incoming secured client connection
version
version of the engine

Element: PluginConfiguration
This is the root element of the plug-in configuration. The settings are loaded after the base configuration is loaded.

Used by: Plug-in Configuration

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

Attributes:
requires
a comma-separated list of plug-in name(s) which this configuration is dependent upon. As of TPTP 4.0, a version identifier suffix has been added to plug-in names. It consists of an underscore character followed by the version number for the release. For example: org.eclipse.tptp.platform.agentcontroller_4.0.0. To ensure plaug-in compatibility for applications that have dependencies on plug-ins from earlier releases (plug-ins that do not have a version identifier suffix), you have the option of specifying the plug-in name for the "requires" attribute excluding the version identifier. In this case, the Agent Controller's configuration loader will first try to locate the full plug-in name including the version identifier suffix. If unsuccessful, the configuration loader then searches for the plug-in name excluding the version identifier suffix. If there is more than one plug-in with the same name, the first plug-in name returned by the operating system will be used.

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 specifies 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 specifies 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 plug-in configurations

Used by: AgentControllerConfiguration

Attributes:
path
fully qualified directory to look for plug-in 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



(C) Copyright IBM Corporation 2000, 2006. All Rights Reserved.