The serviceconfig.xml File

The serviceconfig.xml File

Contents

Introduction
Agent Controller Configuration
Elements and Attributes
Example serviceconfig.xml File

When referring to file and directory locations in this document, <install-home> is the directory where the Agent Controller package was unzipped. This directory is also referred to as %TPTP_AC_HOME% in the configuration files.

Introduction

The serviceconfig.xml file is read by the Agent Controller to obtain user-configurable settings. It is read only once, at startup. Modifications to this file are typically restricted since any changes impact all users.
The serviceconfig.xml file contains the following segments:

Agent Controller Environment Environment variable settings which are applied to the existing environment according to the specified position. The resulting environment becomes the default for all agents and applications subsequently launched via the Agent Controller. This default can be modified later for specific launch requests.
Logging Severity level of information that should be written to the common log file, the format of this information, and the location of the log file. The log file name is servicelog.log .
Agent Location of a directory identifying Agents that should be known to the Agent Controller. Each subdirectory under the main agents directory contains an agent.xml file. All subdirectories at the specified path are expected to represent names of Agents that can be used by a Client. The agent.xml file within each subdirectory typically contains information on how to start the Agent.
Plugin Location of a directory identifying extensions to the serviceconfig.xml file. Each subdirectory under the main plugins directory may contain a pluginconfig.xml file which adds additional elements to the overall configuration. These files usually describe components that are associated with the Agent Controller such as the test session component or the Java Probekit extension.
Process Controller Pathname of the Agent that the Agent Controller will use to launch Agents and applications.
Connection Information used by the Agent Controller and Agents to establish several different types of connections that are used for communication. Each type of connection is described in a Transport Layer block containing different elements according to the type of connection being described.
Application Aliases Set of alternate names (i.e., aliases) for starting applications that use predefined launch information. This allows platform-specific launch information for specific applications to be contained on the target platform. This segment makes it possible to restrict the list of applications that can be launched to those specified in this list.
Peer Connection Transport Transport layer that will be used if the Agent Controller needs to establish a connection with a peer agent controller. This is used when an Agent Controller is invoked with the -shutdown option to shutdown an existing instance. It is also the mechanism used to support the peer monitoring feature.

If the environment variable TPTP_AC_HOME is defined, the Agent Controller looks for config/serviceconfig.xml relative to the path defined by it, otherwise it looks relative to its own installed location. The default location for the serviceconfig.xml file is <install-home>/config/serviceconfig.xml.
Each instance of an Agent Controller running on the same system requires its own version of serviceconfig.xml with different transport layer configurations.

Agents also read the serviceconfig.xml file to get the information from the Connection segment, thus allowing an Agent to communicate with a particular Agent Controller.

Agents read their command line to get an alternate location in which to find the serviceconfig.xml file. The predefined option name for specifying the location is -serviceconfig followed by the pathname of the configuration file. If not specified on the command line, the agent looks for serviceconfig.xml in the same locations as described above for the Agent Controller.

Agent Controller Configuration

The hierarchy of the elements contained in the serviceconfig.xml file is shown below. The order of elements shown at the same level is unimportant. Only one occurrence of each of the first level of elements (i.e. AgentControllerEnvironment, Logging, Agent, Plugin, ProcessController, Connection, ApplicationAliases, PeerConnectionTransport) is expected. Hyperlinks in the hierarchy link to the formal element description in the Elements and Attributes section.

AgentControllerConfiguration
    AgentControllerEnvironment
        Variable
    Logging
    Agent
    Plugin
    ProcessController
    Connection
        TransportLayer
            Configuration
                Port
                PipeName
                MemName
                SecuredPort
                FilePort
                IsDataMultiplexed
                ProcessPolling
                JVM
                Version
                SecurityEnabled
                UserDefinition
                Keystore
                KeystorePassword
                Hosts
                    Allow
                    Deny
    CommandExtractor
    ApplicationAliases
        Application
            Variable
            Parameter
     PeerConnectionTransport

Elements and Attributes

Element: AgentControllerConfiguration
This is the root element of the Agent Controller configuration. The settings are used by the Agent Controller as it first starts up. There can be only one of each sub-element.

Sub-elements:     AgentControllerEnvironment
                            Logging
                            Agent
                            Plugin
                            ProcessController
                            Connection
                            ApplicationAliases
                            PeerConnectionTransport

Element: AgentControllerEnvironment
Defines the global environment settings for all applications and agents launched through the Agent Controller. If this element is omitted, the environment passed on remains identical to that of the Agent Controller itself. Variables defined here do not affect the environment settings of the Agent Controller itself.

Used by: AgentControllerConfiguration

Sub-elements: Variable

Element: Variable
This Variable element defines an environment variable and how it should be positioned within the existing environment to form the default environment for all applications and agents launched. There can be zero or more of these elements defined for the AgentControllerEnvironment

Used by: AgentControllerEnvironment

Attributes:

name

This string value specifies the name of the environment variable.

value

This string value specifies the value of the environment variable.

position

(optional) This string value is one of "append", "prepend", or "replace", indicating where to place this environment relative to the default environment.

Element: Logging
Defines the severity level of information to log, in which format, and to which location. If this element is omitted, all critical and severe warnings will be logged, using CBE format, into the same directory in which the Agent Controller is running. Note that the log file name (tptpAgentCtrl.log) is not configurable; only its location.

Used by: AgentControllerConfiguration

Attributes:

level

(optional) This string value indicates the level of severity of messages that should be logged. Each level includes itself and all events that are more severe. Specify one of the following (listed in order of increasing severity):

DEBUG - includes messages that provide low-level details about the internal flow of code execution of the Agent Controller and agents.
INFORMATION - includes events that are normal but may be of interest to the user of the program.
WARNING - includes events that are unexpected but shouldn't interfere with program operation.
CRITICAL - (default) includes events that indicate normal program operation was interrupted by an error.
SEVERE - is restricted to events that result in program termination.

format

(optional) This string value specifies the format to use when writing the messages to the log file. Specify one of the following:

CBE - (default) messages will be written in Common Base Event format (includes detailed information on the context and origin of the message) suitable for consumption by a CBE log reading utility.
Simple - messages will be written as simple text.

directory

(optional) This string value specifies the location in which the log file will be created. The default is the directory from which the Agent Controller is run.

Element: Agent
This required element specifies the directory in which agents that will be known to the Agent Controller will have placed subdirectories that identify the agent by name and contain an agent.xml configuration file with information on how to launch and manage the agent.

Used by: AgentControllerConfiguration

Attributes:

path

This string value specifies the full pathname of the directory in which to look for agent configurations.

Element: Plugin
This element specifies the directory in which extensions to the Agent Controller configuration will have been placed. The extensions are defined in pluginconfig.xml configuration files. The subdirectories under the specified directory may also contain extension-specific executable files.

Used by: AgentControllerConfiguration

Attributes:

path

This string value specifies the full pathname of the directory in which to look for extensions.

Element: ProcessController
ProcessController element simply contains a value which specifies the pathname of the executable which the Agent Controller will start and then call upon to launch agents and applications. By default, the Agent Controller will launch the tptpProcessController(.exe) agent located in the same directory as the Agent Controller itself. The executable must register itself with the Agent Controller and be able to process the command set for that interface. Because its launch information is restricted to the pathname contained here, this agent is not required to have a subdirectory specified in the agents directory like other agents and it cannot take command line arguments.

Used by: AgentControllerConfiguration

Element: Connection
This element is required and, at a minimum, must contain a TransportLayer element to define each of the following types of connections which are used by the Agent Controller: socket, named-pipe, and shared memory.

Used by: AgentControllerEnvironment

Sub-elements: TransportLayer

Attributes:

name

This string value provides a name for the connection configuration.

Element: TransportLayer
This element defines a Transport Layer which is a pluggable component inside the Agent Controller responsible for sending and receiving data between components in the system via an interprocess communication mechanism.

Used by: Connection

Sub-elements: Configuration
                         CommandExtractor

Attributes:

loadlib

This string value specifies the name of the library to be loaded for this transport layer, without its suffix (i.e., do not include .dll or .so). The normal system path search for locate the library is used.

type

This string value provides the specific identity of this transport layer. The possible values are: TPTP_SOCKET, TPTP_NAMEDPIPE, TPTP_SHAREDMEM, TPTP_CCTL and TPTP_ACTL. Custom transport layers will use other identifiers. The TPTP_CCTL and TPTP_ACTL values are custom transports that provide backward compatibility for clients and agents using the original Agent Controller interfaces.

Element: Configuration
The Configuration element contains a sub-element that specifies the interprocess communication mechanism for each TransportLayer. The communication mechanisms provided for here are socket, named-pipe, shared memory and CCTL. The ACTL transport layer has no configuration elements. Custom TransportLayers might have other configuration elements that are specific to those transport layers.

Used by: TransportLayer

Sub-elements:     Port (only with socketTL and CCTL)
                            PipeName (only with namedPipeTL)
                            MemName (only with sharedMemTL)
                            SecuredPort (only with CCTL)
                            FilePort (only with CCTL)
                            IsDataMultiplexed (only with CCTL)
                            ProcessPolling (only with CCTL)
                            JVM (only with CCTL)
                            Version (only with CCTL)
                            SecurityEnabled (only with CCTL)
                            UserDefinition (only with CCTL and only if security is enabled)
                            Keystore (only with CCTL and only if security is enabled)
                            KeystorePassword (only with CCTL and only if security is enabled)
                            Hosts (only with CCTL)

Element: Port
The Port element specifies the port to be used for socket communication. The Port element is only valid when used with the TPTP_SOCKET and TPTP_CCTL transport layers. Its integer value specifies the actual port number to use in making the socket connection.

Used by: Configuration

Element: PipeName
The PipeName element indicates the transport layer is for named-pipe communication. The PipeName element is only valid when used with the namedPipeTL loadlib. Its string value specifies the name of the pipe to use in making the connection.

Used by: Configuration

Element: MemName
The MemName element indicates the transport layer is for shared memory communication. The MemName element is only valid when used with the sharedMemTL loadlib. Its string value specifies the name of the shared memory resource to use in making this connection.

Used by: Configuration

Element: SecuredPort
The SecuredPort element specifies the port to be used for secure socket communication. The SecuredPort element is only valid when used with the TPTP_CCTL transport layer. Its integer value specifies the actual port number to use in making the secure socket connection.

Used by: Configuration

Element: FilePort
The FilePort element specifies the transport layer used for socket communication by the File Transfer service. The FilePort element is only valid when used with the TPTP_CCTL transport layer. Its integer value specifies the actual port number to use in making the socket connection.

Used by: Configuration

Element: IsDataMultiplexed
The IsDataMultiplexed element specifies 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. This element takes a Boolean value that defaults to "FALSE". The IsDataMultiplexed element is only valid when used with the TPTP_CCTL transport layer.

Used by: Configuration

Element: ProcessPolling
The ProcessPolling element specifies whether or not active checking of process status is enabled. This attribute is used to make sure the Agent Controller detects when a process has terminated. This element takes a Boolean value that defaults to "TRUE". The ProcessPolling element is only valid when used with the TPTP_CCTL transport layer.

Used by: Configuration

Element: JVM
The JVM element specifies the fully qualified path of the JVM dynamic runtime library (jvm.dll or libjvm.so) to be used by the File Transfer and secure connection components. The JVM element is only valid when used with the TPTP_CCTL transport layer.

Used by: Configuration

Element: Version
The Version element describes the version number of the Agent Controller that will be reported to other components. The Version element is only valid when used with the TPTP_CCTL transport layer.

Used by: Configuration

Element: SecurityEnabled
The SecurityEnabled element indicates whether or not clients connecting to this transport layer must connect to the secure port. If security is enabled and a client attempts to connect to the non-secure port, the client will be given the address of the secure port and the connection will be refused. This element takes a Boolean value that defaults to "FALSE". The SecurityEnabled element is only valid when used with the TPTP_CCTL transport layer.

Used by: Configuration

Element: UserDefinition
The UserDefinition element describes which users may connect to this transport layer. If this element is set to "ANY", all users which can be authenticated with the OS will be allowed to connect. If security is enabled, this element is required. This element takes a string value consisting of a comma separated list of user names. The UserDefinition element is only valid when used with the TPTP_CCTL transport layer.

Used by: Configuration

Element: Keystore
The Keystore element specifies the location of the keystore for secure connections. If security is enabled, this element is required. The Keystore element is only valid when used with the TPTP_CCTL transport layer.

Used by: Configuration

Element: KeystorePassword
The KeystorePassword element sets the password to be used with the keystore for secure connections. If security is enabled, this element is required. The KeystorePassword element is only valid when used with the TPTP_CCTL transport layer.

Used by: Configuration

Element: Hosts
The Hosts element is used to control which hosts are allowed to connect through this transport layer. This element consists of one or more Allow or Deny elements. The Hosts element is only valid when used with the TPTP_CCTL transport layer.

Used by: Configuration

Element: Allow
The Allow element specifies a Host allowed to connect to the Agent Controller through this transport layer.

Used by: Hosts
Attributes:

host

This string is the name or IP address of the host. A value of "ALL" indicates that this transport layer may accept connections from any host. A value of "LOCAL" indicates that connections should be accepted from local processes.

net

This attribute indicates a subnet from which to allow connections.

mask

This attribute indicates a subnet mask to use to allow connections.

Element: Deny
The Deny element specifies a Host not allowed to connect to the Agent Controller through this transport layer.

Used by: Hosts
Attributes:

host

This string is the name or IP address of the host to deny.

net

This attribute indicates a subnet from which to deny connections.

mask

This attribute indicates a subnet mask to use to deny connections.

Element: CommandExtractor
This element defines a Command Extractor which is a pluggable component in a Transport Layer that extracts commands from the interprocess communication stream. Its string value specifies the name of the library to be loaded without its suffix (i.e., do not include .dll or .so) or prefix (i.e., "lib" for Linux). The normal system path search for locate the library is used.

Used by: TransportLayer

Element: ApplicationAliases
The ApplicationAliases element is an optional list of application alias definitions.

Used by: AgentControllerConfiguration

Sub-elements: Application

Attributes:

launchAliasesOnly

(optional) This string attribute is either "true" or "false" (default). If set to "true", only applications that have been defined within this element will be launched. If the attribute is set to "false" or omitted, any application can be launched.

Element: Application
The Application element defines an alias name and launch information for an application.

Used by: ApplicationAliases

Sub-elements: Variable
Parameter

Attributes:

executable

This string value specifies the alias name for the application executable specified in the path attribute.

location

(optional) This string value specifies the directory from which the executable is to be launched, sometimes referred to as the working directory for the executable while it is running.

path

This string value specifies the full pathname of the application to launch. This is used in place of the alias name when launching the application executable.

Element: Variable
This Variable element defines an environment variable and how it should be positioned within the existing environment when the application is launched. There can be zero or more of these elements defined for an Application.

Used by: Application

Attributes:

name

This string value specifies the name of the environment variable.

value

This string value specifies the value of the environment variable.

position

(optional) This string value is one of >"append", "prepend", or "replace", indicating where to place this environment relative to the default environment.

Element: Parameter
The Parameter element defines a command line argument to be given the application when launched. There can be zero or more of these elements defined for an Application.

Used by: Application

Attributes:

value

This string value specifies a command line argument.

position

(optional) This string value is one of "append", "prepend", or "replace" indicating where to place this argument relative to the existing command line arguments.

Element: PeerConnectionTransport
This required element specifies the transport layer which will be used to establish connections between the Agent Controller reading this configuration and peer Agent Controller instances. The value name of this element must match a Transport Layer type name for a specific transport layer declared in the Connection section of the configuration file (e.g. TPTP_CCTL).

Used by: AgentControllerConfiguration

Example serviceconfig.xml File

This example shows a sample Agent Controller configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<AgentControllerConfiguration>
    <AgentControllerEnvironment configuration="default">
        <Variable name="JAVA_PATH" value="C:\Program Files\Java\j2re1.4.2_08\bin\java.exe" position="replace"/>
        <Variable name="RASERVER_HOME" value="C:\Eclipse\Projects\AgentController" position="replace"/>
        <Variable name="TPTP_AC_HOME" value="%RASERVER_HOME%" position="replace"/>
        <Variable name="PLUGINS_HOME" value="%RASERVER_HOME%\plugins" position="replace"/>
        <Variable name="PATH" value="%RASERVER_HOME%\bin" position="prepend"/>
    </AgentControllerEnvironment>
    <ApplicationAliases>
        <Application configuration="default" executable="java.exe" path="%JAVA_PATH%" location="%SYS_TEMP_DIR%">
            <Variable name="CLASSPATH" value="%CLASSPATH_ORG_ECLIPSE_EQUINOX_COMMON%" position="append"/>
            <Variable name="PATH" value="%RASERVER_HOME%\bin" position="prepend"/>
        </Application>
    </ApplicationAliases>
    <Plugin path="%PLUGINS_HOME%"/>
    <Agent path="%TPTP_AC_HOME%\agents"/>
    <Logging level="INFORMATION" format="CBE" directory="%TPTP_AC_HOME%\config"/>
    <ProcessController>%TPTP_AC_HOME%\bin\tptpProcessController.exe</ProcessController>
    <Connection name="Dev">
        <TransportLayer loadlib="socketTL" type="TPTP_SOCKET">
            <Configuration>
                <Port>10006</Port>
            </Configuration>
            <CommandExtractor>tptpCmdExtr</CommandExtractor>
        </TransportLayer>
        <TransportLayer loadlib="namedPipeTL" type="TPTP_LOG">
            <Configuration>
                <PipeName>acmasterlog</PipeName>
            </Configuration>
            <CommandExtractor>tptpCmdExtr</CommandExtractor>
        </TransportLayer>
        <TransportLayer loadlib="namedPipeTL" type="TPTP_NAMEDPIPE">
            <Configuration>
                <PipeName>acmaster</PipeName>
            </Configuration>
            <CommandExtractor>tptpCmdExtr</CommandExtractor>
        </TransportLayer>
        <TransportLayer loadlib="sharedMemTL" type="TPTP_SHAREDMEM">
            <Configuration>
                <MemName>acbuffer</MemName>
            </Configuration>
            <CommandExtractor>tptpCmdExtr</CommandExtractor>
        </TransportLayer>
        <TransportLayer loadlib="tptpCCTL" type="TPTP_CCTL">
            <Configuration>
                <Port>10002</Port>
                <SecuredPort>10003</SecuredPort>
                <FilePort>10005</FilePort>
                <IsDataMultiplexed>false</IsDataMultiplexed>
                <ProcessPolling>true</ProcessPolling>
                <Jvm>C:\Program Files\Java\j2re1.4.2_08\bin\client\jvm.dll</Jvm>
                <Version>4.2.0</Version>
                <SecurityEnabled>true</SecurityEnabled>
                <UserDefinition>ANY</UserDefinition>
                <Keystore>C:\Eclipse\Projects\AgentController\security\tptpSampleKeystore</Keystore>
                <KeystorePassword>password</KeystorePassword>
                <Hosts configuration="default">
                    <Allow host="LOCAL"/>
                </Hosts>
            </Configuration>
            <CommandExtractor>tptpCmdExtr</CommandExtractor>
        </TransportLayer>
        <TransportLayer loadlib="tptpACTL" type="TPTP_ACTL">
            <Configuration/>
            <CommandExtractor>tptpCmdExtr</CommandExtractor>
        </TransportLayer>
    </Connection>
    <PeerConnectionTransport>TPTP_CCTL</PeerConnectionTransport>
</AgentControllerConfiguration>

Copyright (C) 2005, 2007 Intel Corporation.

Error 404 - Not Found
Error 404 - Not Found
The document you are looking for may have been removed or re-named. Please contact the web site owner for further assistance.

Agent Controller Environment	Environment variable settings which are applied to the existing environment according to the specified position. The resulting environment becomes the default for all agents and applications subsequently launched via the Agent Controller. This default can be modified later for specific launch requests.
Logging	Severity level of information that should be written to the common log file, the format of this information, and the location of the log file. The log file name is servicelog.log .
Agent	Location of a directory identifying Agents that should be known to the Agent Controller. Each subdirectory under the main agents directory contains an agent.xml file. All subdirectories at the specified path are expected to represent names of Agents that can be used by a Client. The agent.xml file within each subdirectory typically contains information on how to start the Agent.
Plugin	Location of a directory identifying extensions to the serviceconfig.xml file. Each subdirectory under the main plugins directory may contain a pluginconfig.xml file which adds additional elements to the overall configuration. These files usually describe components that are associated with the Agent Controller such as the test session component or the Java Probekit extension.
Process Controller	Pathname of the Agent that the Agent Controller will use to launch Agents and applications.
Connection	Information used by the Agent Controller and Agents to establish several different types of connections that are used for communication. Each type of connection is described in a Transport Layer block containing different elements according to the type of connection being described.
Application Aliases	Set of alternate names (i.e., aliases) for starting applications that use predefined launch information. This allows platform-specific launch information for specific applications to be contained on the target platform. This segment makes it possible to restrict the list of applications that can be launched to those specified in this list.
Peer Connection Transport	Transport layer that will be used if the Agent Controller needs to establish a connection with a peer agent controller. This is used when an Agent Controller is invoked with the -shutdown option to shutdown an existing instance. It is also the mechanism used to support the peer monitoring feature.