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:
configurationname 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:
pathfully 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