Installation

There are 2 file archives to be used in the installation:

After installation, customization should be performed. See the Configuration sections below for details.

The type of service(s) that you intend to deploy will dictate which version of xmarc.war you need to copy. In actual fact, es/xmarc.war is just a subset of wiise/xmarc.war.

Servlets Installation - Deploying the Xmarc web application

The Service Manager and Service Broker are made up of servlets and their supporting files, all of which have been archived into a Web application archive file. Such an archive is known as a WAR file and ends with a .war file extension. The deployment of WAR files requires that the servlet container comply to Sun's 2.2 (or higher) Servlet specification.

Deployment of the Service Manager and Service Broker is achieved by simply moving the appropriate xmarc.war (see above) into the particular servlet container’s Web application deployment directory. For example web applications are deployed in the webapps directory of Jakarta-Tomcat. See your servlet container's documentation for details. Then simply restart the servlet container.

Once the Service Manager and Broker servlets have been installed on the Web Server, there is no subsequent servlet configuration required.

Important: you will need to enter a password when presented with the Administration Login screen. Upon installation the default value has been set to (uppercase) "X". It is recommended that this password be changed from its initial setting.

Important: Xmarc client-side products are not fully HTTP 1.1 compliant as they do not support "chunked" encoding (refer to Hypertext Transfer Protocol -- HTTP/1.1 RFC 2616). Consequently most HTTP servers (such as Apache) and servlet containers running in a standalone mode (such as Tomcat) will need to be configured appropriately in order to force a protocol exchange using HTTP 1.0 (instead of 1.1) . To allow filtering of HTTP requests by web servers, all requests originating from Fire clients will have their HTTP User-Agent header set to "Formida Fire".

Service Agent Installation

The Service Agent is a Java program that will typically operate as an NT service or Unix daemon process. A prerequisite to installing the Agent is that the host must have a properly installed and configured Java Virtual Machine (JVM). The Agent is compatible with JVM 1.3 and above.

The command line syntax for the Service Agent is defined as follows:

java com.xmarc.agents.AgentX [-prop <propfile>]

although this should never be called directly because it is invoked automatically by a service wrapper program agentx (see below).

The -prop switch defines the name and location for a properties file used to initialize AgentX. Each agent will have its own properties file, so this switch is always necessary.

NT Installation

A supplementary program is provided in order to allow the Service Agent to run as an NT service. The zip file contains an executable: agentx.exe.

  1. Install and configure a Java Virtual Machine. This must be 1.3 compliant or above.

  2. Unzip agentx.zip into an appropriate directory (for example C:\xmarc\AgentX).

  3. Change to this directory. You should see the following files:

    4. agentx.exe, AgentX.jar and agentx.properties.

  4. Edit any system dependent entries in the agentx.properties file. You should rename the file before editing. See below for the property file details.

  5. Now install AgentX as an NT service by executing the following DOS command:

    6. agentx /install:"Agent Name" [/interact:{true|false}] [/prop:agentx.properties]

    If more than one agent is running, then "Agent Name" text must be distinct, and each agent will have its own property file.

  6. The NT Services panel should now show an entry with the name defined by "Agent Name". The Service Agent may now be started and stopped like other NT services by clicking the start/stop icons in the Services panel.

The figure below shows the NT Services Panel after AgentX has been successfully installed as an NT service. AgentX was installed with an agent name set to "Xmarc Engine Services".

Note: set interact to true if the service displays a user interface. For example, installing AgentX to manage Fire requires interact be set to true. The service must run in the context of the LocalSystem account in order to be marked "interactive". Setting the service to be interactive can be done via the command line when installing AgentX or via the Properties menu for Xmarc Engine Service as shown below.

It is important to understand the implications of running Agentx under the security context of the LocalSystem account or that provided by a User account.

Typically AgentX is run under the LocalSystem account, thereby affording the AgentX process the privileges experienced by any system process. However there are limitations: the system account is not associated with a particular user, so it cannot access profile information for any other account. In addition the service only has access to limited network resources (although a service can access network resources that explicitly grant access to the "machine" account of the computer on which the service is running).

This means that when running under the LocalSystem account, AgentX and the programs it spawns, should not access any network mounted resources (i.e. manage data and programs residing on network drives). If this is attempted, the drives will appear inaccessible or in the worst case it will appear that the AgentX process has hung. All programs spawned by AgentX should be locally accessible!

Running a service in a user account will typically allow access to network resources. However the service doesn't have access to the console thereby make a service running in a user account incompatible with a window-based application. If you intend to use AgentX to launch a window-based application (as is the case with a FireRender service) AgentX must be run in the LocalSystem account with desktop interaction set (see above for details on how to set this), with the inherent restrictions on accessing network drives.

Important: The Sun JVM registers a console control handler which begins shutdown-hook processing for the following console events: CTRL_C_EVENT, CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT CTRL_SHUTDOWN_EVENT. In order to run the JVM as a service and remain running after a user session has ended (i.e. a CTRL_LOGOFF_EVENT has been fired), the JVM must be informed to not install its own console handlers. This is done via the -Xrs JVM option. Consequently, in order to keep the AgentX service from terminating after a user logs off, make sure the following agentx property is set to include the -Xrs switch:

agentx.jvm.options = -Xrs

If the agent failed to start, this is often because the path to the Java Virtual Machine dll or that to the AgentX.jar is incorrect in the properties file:

agentx.jvm.path=c:/j2sdk1.4.0/jre/bin/server/jvm.dll
agentx.classpath=c:/Xmarc/AgentX/AgentX.jar

In such cases the reason for failure can usually be found in the services Event Viewer log(Control Panel/Administrative Tools/Event Viewer). You may then have to uninstall the service before you can re-install, after first correcting the error in the properties file of course.

Uninstalling the service can be done with the following DOS command:

agentx /remove:"Agent Name"

where "Agent Name" is the same text you used to install it.

Unix Installation

A supplementary program is provided in order to allow the Service Agent to run as a Unix daemon process. This is supplied in a platform-dependent tar file and is named agentx. There is also a shell script: agentxd which is used to start and stop the agent(s). This script is typically placed in the /etc/init.d directory in order for the agent(s) to be started and stopped as the machine is booted and halted.

agentxd

agentxd is a shell script used to start and stop agents. The script will require some minor editing to tell it the location of the agent installation directory, the location of dynamic libraries which the Java VM may require, and a location in which temporary PID (process ID) files are created. The variables that are required to be set are clearly marked via comments within the agentxd file. The script eventually calls an executable program agentx, responsible for starting the Java VM in a separate background process and running the Java code contained in AgentX.jar. One or more agents can be started on a host machine and each instantiation will create a separate process in which the Java VM is run.

Starting agents

Agents may be started in two ways:

1. agentxd start agentx_1.properties agentx_2.properties
2. agentxd start

In the first case (which starts 2 agents),the property files are explicitly passed in as command line arguments. In the second case, the property file information is determined from the agentx shell variable: AGENT_PROPERTY_FILES. For the cases to be equivalent, set the variable as follows:

AGENT_PROPERTY_FILES="agentx_1.properties agentx_2.properties"

This will create 2 separate JVM's. Each will be listening on a unique port determined by the agentx.port property in each property file. It follows that there is a one-to-one mapping of property files to port numbers to agent processes. Continuing with the above example, 2 property files means 2 agentx processes and 2 listening ports.

Stopping agents

Agents may be stopped in two ways:

1. agentxd stop 22000 22001
2. agentxd stop

In the first case, the agents to be halted are explicity identified, by passing in as command line arguments, their respective port numbers that each agent is listening on. The port numbers are then used to identify the agent's process ID which is then sent a SIGHUP signal. In the second case, all agentx process will be halted, again with each agent process being sent a SIGHUP.

Solaris 2.x and Linux

  1. Install and configure a Java Virtual Machine

  2. Extract agentx.tar into an appropriate directory (for example /opt/xmarc/agentx)

  3. Change to this directory. You should see the following files:

    4. agentxd, agentx, AgentX.jar and agentx.properties

  4. Become root user

  5. Copy agentxd to /etc/init.d. Edit any system dependent entries in the agentx shell script. This should involve setting the AGENT_HOME script variable to the directory in which the .tar file was expanded (in our example - /opt/xmarc/agentx).

  6. The script may be started by running the following command:

    7. /etc/init.d/agentxd start [<property filename1> [<property filename2>...]]

  7. Stop the agent by running the following command:

    8. /etc/init.d/agentxd stop [<agent port 1> [<agent port 2>...]]

  8. Make the necessary links into the /etc/rc directories in order for agentx to start automatically on boot up and to terminate on system shutdown.

Service Agent Configuration

On startup, the Service Agent reads a configuration (or properties) file. This provides various environment options and can be tailored for a particular host and services. By default, the properties file used is the one in the same directory as the Service Agent program, and is named agentx.properties. However, a different properties file should be used by copying and renaming the one supplied and then adding an appropriate command line parameter to the Service Agent invocation command.

Note: All directory paths should use the / separator.

An example of the properties file template is shown below. Note that properties which can be set are marked in blue, those properties which are likely to need changing for your installation are marked in red. Uncomment where necessary. You will notice that the file paths are in Windows notation. For a Unix installation, paths will require appropriate "unixification".

###############################################################
##
## Filename: agentx.properties
##
## Description: AgentX Properties File Template
##
## Author: Xmarc
##
## MODIFICATIONS
##
## COPYRIGHT NOTICE
## (C) Copyright 2003 Xmarc Ltd
##        All rights reserved.
##
###############################################################
# IMPORTANT:
# ==========
 
# <AGENT_HOME> should be replaced by wherever the AgentX files
# have been installed, e.g. for MS Windows - C:/Xmarc/agentx
 
# This file should be renamed from agentx.properties to <desc>.properties
# where <desc> reflects the services which will be launched by the agent.
 
# Note: The directory path name separator should be /. Do not use \.
###################### General Properties #####################
 
# The Service Agent Listening Port:
# This is the port number on which AgentX will accept requests,
#   e.g. from a Service Manager.
# Each agent running on a particular host must have a different value.
# We advise starting at 22000.
agentx.port=22000
 
# Description to appear in a services panel, e.g. Windows services
# Tailor this to differentiate between multiple agents
agentx.description=Controls service life-cycle as directed by Xmarc Service Manager
 
# Where the Xmarc license server can be found.
# If omitted, localhost:2001 is used.
#agentx.license_server=myhost:2001
####################### JVM details #######################
 
# The full pathname to Java's VM dll. If this value is modified 
# the agentx service (which is really the Java VM) will 
# need to be restarted for the value to take effect. All class 
# objects and instances therein will be destroyed.
# For unix platforms simply set this property to the
# JVM shared library. For example, on a Linux-based
# platform is should be set as follows:
#     agentx.jvm.path=libjvm.so
# To load correctly, the LD_LIBRARY_PATH environment
# variable must be correctly set. This is done automatically
# via the agentxd shell script that is provided.
# For a windows platform, the following might be used for an
# installation with Sun's Java 1.4
agentx.jvm.path=c:/j2sdk1.4.0/jre/bin/server/jvm.dll
 
# CLASSPATH environment that is passed to the JVM ...
# Note: If more than one line is supplied, these will be
#       concatenated and separated by ";" automatically.
# Uncomment the following line if you are using a version
#   of Java prior to 1.2, and replace JAVA_HOME with the directory
#   where Java is installed
#agentx.classpath=<JAVA_HOME>/jre/lib/rt.jar
 
# Uncomment and set the following line to where you installed
#   the AgentX.jar file, i.e. <AGENT_HOME>/AgentX.jar
agentx.classpath=c:/Xmarc/AgentX/AgentX.jar
 
# Uncomment and amend the following statement to add the location
#   of any classes used by the Java services which AgentX
#   will launch. Note: this does not include the top-level service
#   classes which, for "hot deploy" purposes, should be specified
#   by the agentx.enginepath property explained later.
#agentx.classpath=c:/Xmarc/WIISE/service/lib/xcore.jar
 
# Uncomment the following line if you wish to pass down any Java VM 
#   non-standard options. Options may vary between various Java
#   implementations. Separate multiple options with the "|" character.
# For example to pass an argument informing Sun's Java VM to set the 
#   initial and maximum heap size:
#agentx.jvm.options=-Xms20m|-Xmx200m
# Typically on Windows NT, the following option will be necessary to keep
#   an agent running after user log-off
agentx.jvm.options=-Xrs
 
# The main class name (entry point). This is the class that the Java
#   VM initially loads. If no value is given, it defaults to "AgentX".
#agentx.service_class=
 
# This defines the method (function name) that acts as the entry
#   point for the VM upon loading the class defined by the
#   agentx.service_class property. This method must return void and takes
#   a String array as an argument. If no value is given, it defaults
#   to a method called "main".
#agentx.service_class.start_method=
 
# Add any command line arguments that are passed to the method defined
#   by the agentx.service_class.start_method property.
#agentx.cmd_line=
 
# This defines the class which will be loaded upon AgentX being termminated.
#   If no value is given, it defaults to "com/xmarc/fjsvc/FJFxServer.class"
#agentx.service_shutdown_class=
 
# Upon AgentX being terminated (and hence the VM will be shutdown), a call 
#   will be made to the method name defined here, allowing the application 
#   to perform any tidying up before the VM finally terminates. If no
#   value is given, it defaults to a method called "shutdown".
#agentx.service_stop_method=
################## Message/Debug Logging  ####################
 
# Java VM logging: Any output by the Java VM itself will be
# redirected to the file specified here.
#agentx.jvm.log=c:/Xmarc/es6.1/logs/agentjvm.log
 
# AgentX debug logging:
# These properties direct all AgentX log information to a file. 
# Debug levels control the amount of information logged.
# The higher the number the greater the amount of information logged.
# This should be disabled if everything is functioning correctly
#   to avoid large log file sizes.
# Make sure that the directory exists and you have write 
#   access to this file.
#    agentx.debug_file=<agentx_log>
#    agentx.debug_level=<level: 0|1|2|3|4>
# Timestamps can be prefixed to all logged messages.
# The default is set to "off" - i.e. no timestamp information.
#    agentx.debug_show_timestamp=<on|off>
# Typical values:
agentx.debug_file=c:/Xmarc/es6.1/logs/agentdebug.log
agentx.debug_level=1
agentx.debug_show_timestamp=off
 
# Base name of the file(s) used for service logging.
agentx.logfileprefix=c:/Xmarc/es6.1/logs/agent
 
# Maximum number of lines permitted per log file.
# Once the maximum number of lines is reached, a new
# log file is created (unless the logfilecount has been
# reached) and logging output is now directed to the
# new file.
agentx.loglinemax=1024
 
# Maximum number of service log files. Once the final log file has
# reached its maximum line count, output will then be directed
# back to the first log file that was created. Any previous
# file contents are lost.
agentx.logfilecount=3
##################### Search Paths  #########################
 
# Direct AgentX where to find the service X engine class files.
# This is only required when Java services (X engines) are to be deployed.
# Please note: this should define a directory, zip or jar file which contains
#   the engine (service) class files. In order for "hot deploy" to function 
#   correctly they must NOT exist anywhere within CLASSPATH, which is set
#   by agentx.classpath.
# This property takes a URL formated string to define the class file location.
# For example if XLocator.class is in the directory C:/temp then set this
# property as follows:
#      agentx.enginepath=C:/temp
# if the class is in a local jar file, set it as follows:
#      agentx.enginepath=C:/temp/xlbs.jar
# if the class is in a jar file on a web server, set it as follows:
#      agentx.enginepath=http://engines/lib/xlbs.jar
# There can be as many agentx.enginepath statements as necessary, and
#   AgentX will concatenate them to form the full path
#agentx.enginepath=<ENGINE_LOCATION>
 
# Directory or directories that contain all launchable executables,
#   e.g. database interfaces, translators, fire etc., but not X engines
# Note: If more than one line is supplied, these will be
#       concatenated and separated by ":" for Unix or ";" for Win32.
# Note: In order for AgentX to launch a process service,
#       the executable MUST BE LOCATED in one of the listed directories.
#       If there are occurrences of the executable in multiple directories, the
#       first one found is used.
#       This is only required if the agent is required to launch
#       process services. X engines are not process services.
# e.g. for an ES installation, assuming an install directory of c:/Xmarc/es6.1
agentx.bin=c:/Xmarc/es6.1/fire/mx/i386/win32/bin
 
# e.g. for a WIISE LBS installation, assuming an install directory of c:/Xmarc/WIISE
#agentx.bin=c:/Xmarc/WIISE/service/fx/i386/win32/bin
 
# Command used by AgentX to terminate rogue processes.
# If not set, a default program is used in an attempt to terminate the process.
# For Windows, the program supplied is fxpurge.exe.
# For Unix, the Unix kill command is used.
# Note: For recent Windows versions (e.g. XP), it should be set to tskill.exe.
#       This is normally located in your <WINDOWS>/system32 directory.
#       The searchpath defined by agentx.bin should then be augmented
#       to locate the termination command.
#agentx.termination_command=tskill.exe
#agentx.bin=c:/windows/system32
################## Environment Variables  ######################
 
# Any key name that contains ".envvar." directs AgentX to
# create an environment that will be inherited by any
# launched (child process) service (not Java engines).
# e.g.
#      agentx.envvar.myvar=whatever
# Values may contain $ references to system environment variables.
# Note:  .envvar properties are the ONLY properties which
#   may contain references to system environment variables.
 
# Path environment that is passed to the JVM and any services.
# Note: If more than one line is supplied, these will be
#       concatenated separated by ":" for Unix or ";" for Win32.
#       Directories containing any dynamic libraries required
#       by a launched process service MUST BE listed here.
#       A typical example is fx8i/fx9i which needs to pick up Oracle libs.
agentx.envvar.path=$path;C:/Oracle/Ora816/Bin
 
# A user's environment variable picking up a system value
#agentx.envvar.MXTEMPDIR=$MXTEMPDIR
 
# System properties to be inherited by Java Services (X engines).
# These values can be accessed within X engine Java via the
# System.getProperty method, e.g.
#      agentx.system.myvar=whatever
# would be available via the call System.getProperty("myvar")
#agentx.system.myvar=LemonGrass
################## WIISE LBS Services only ######################
 
# Engine activity logging may be directed to an activity
# service by setting the following 2 lines:
#   url     specifies the url of the activity service
#   bufsize specifies how many transactions are buffered
#           before being sent to the activity service 
# NOTE: This property is for WIISE installations only.
#agentx.system.activity.url=sm:XACTIVITY:///servlet/WIISE
#agentx.system.activity.bufsize=100
 
# Note: For the above to take effect, an Engine must have the line
#   activity.url=agent
# in its properties file. Any other activity.url in an
# Engine's property file will take precedence.
# If there is no activity.url present in an Engine's property file,
# no activity logging will be performed for that Engine.
 
# The name of the Service Config servlet:
# This servlet provides site-specific parameters on request
# for starting X-engines from the WIISE API level or from
# other X engines. The default value is WIISEServiceConfig
#agentx.system.serviceconfig=WIISEServiceConfig
 
# The name of a cache directory. Some WIISE engines require a directory
# in which to cache files. This can be set in an engine's property
# file via a "cache" property, or set in the agent via this property.
#agentx.system.engine.cache=c:/temp
 
# The default 2-character iso country code for engines launched by
# the agent. An engine can override this via the "country" property
# in its own property file.
#agentx.system.engine.country=GB
# End agentx.properties

If for any reason, the Service Agent fails to start, the agentx log file should describe why. If AgentX is running on a NT system, additional errors can be viewed via the NT Event Viewer.

The debug level defines the level of debug information dropped into the agentx log file:

0      System errors and service start/stop messages;
1      0 + Client connect and disconnect messages;
2      1 + Application errors;
3      2 + Full command monitoring;
4      3 + Full debug messages

Be aware that running a Service Agent with logging levels greater than 3 generates a great deal of log output. These levels are typically used for debugging purposes only.

License Server

Typically , when running services via an agent, the services will require a license server (i.e. mxserver) to be running as well.

If the license server is to run on the same machine as the agent(s) which launch the services, the license server should also be installed as an NT service or Unix daemon to start/stop at boot/shutdown time. It should be configured to start before the agents.

NT Service

To register the license server as a service, the following NT command should be executed once, typically at a DOS prompt:

mxserver -reg

A quick squiz at the NT Services panel should show a service named Xmarc Fire License Server running.

Unix Daemon

The license server daemon should be configured in a similar manner to the agent daemon. A shell script mxserverd has been provided for this purpose and is supplied in the agent tar file. It can be used to start and stop the mxserver process.

The script should typically be edited and copied to the /etc/init.d directory for the subsequent starting and stopping of the license server at machine boot and shutdown time respectively. The mxserverd script will require some minor editing to set the location of the Fire installation home and a location in which temporary PID (process ID) files are located. The variables to be set are clearly marked via comments within the script.

If there is a requirement to start or stop the license server manually, use the following (as super-user):

/etc/init.d/mxserverd start
/etc/init.d/mxserverd stop

Previous Chapter