Gateway Central - AGM Administrator Guide

Throughout this document, the reader will notice that some filenames are prefixed with numerals (i.e. 02, 03, etc.). This is due to the configuration of the Gateway Central server deploy mechanism. Files that are prefixed with numerals are deployed last, and in numerical order. An example of this is with the Failed Gateway Monitor service. The basic configuration files have no prefix, and the actual service configuration file does. This guarantees that the configurations needed by the Failed Gateway Monitor service are deployed before the actual service is deployed.

AGM leverages the power of MBeans (managed beans) and therefore uses the standard JBoss service XML configuration file format. This is explained in more detail in the Installation section of this document. You will see samples of the configuration files throughout this document.

A Restart configuration defines a script to run when a Gateway fails and an optional restart delay. When a Gateway fails, the script specified in the Gateway's Restart configuration is invoked. Following is a list of the attributes in a Restart configuration along with a description of each attribute:

Following is a sample Restart configuration file that shows a default Restart configuration.

<?xml version="1.0" encoding="UTF-8"?>
<server>
  <mbean code="com.lsft.nx.agm.config.Restart" 
         name="LongviewServer.Service.AGM:restart=DefaultRestart">
  	<attribute name="ScriptName">gcRestartFailedGateway.groovy</attribute>
  	<attribute name="RestartDelay">5</attribute> <!-- 5 seconds -->
  </mbean>
</server>
			

A Threshold configuration defines a threshold for the number of Gateway failures. At its core, a Threshold configuration specifies a threshold count and a threshold period. These two values define the threshold. The threshold count is specified as a simple integer value, and the threshold period is specified in seconds. Therefore, if the threshold count is set to 5 and the threshold period is set to 60, the threshold is defined as 5 failures in 60 seconds. The algortihm used to determine if a threshold has been breached uses a sliding window, so it is possible to actually see the current failure count of a failing Gateway decrease under circumstances where the time between failures is less than the threshold period but large enough that the difference between the most recent failure and the first failure exceeds the threshold period. Under those circumstances, the older failure times are considered to be stale, and they are discarded. In addition to threshold count and threshold period, a Threshold configuration may contain an optional Restart configuration. Following is a list of the attributes in a Threshold configuration along with a description of each attribute:

Following is a sample Threshold configuration file that defines a total failure threshold and a default failure threshold.

<?xml version="1.0" encoding="UTF-8"?>
<server>
  <mbean code="com.lsft.nx.agm.config.Threshold" 
         name="LongviewServer.Service.AGM:threshold=TotalFailureThreshold">
  	<attribute name="ThresholdCount">15</attribute>
  	<attribute name="ThresholdPeriod">6000</attribute> <!-- 10 minutes -->
  	<!-- <attribute name="BreachScript">
	gcTotalFailureThresholdBreach.groovy</attribute> -->
  </mbean>
  
  <mbean code="com.lsft.nx.agm.config.Threshold" 
         name="LongviewServer.Service.AGM:threshold=DefaultThreshold">
  	<attribute name="ThresholdCount">5</attribute>
  	<attribute name="ThresholdPeriod">300</attribute> <!-- 5 minutes -->
	<depends optional-attribute-name="Restart">LongviewServer.Service.AGM:
	restart=DefaultRestart</depends>
  	<!-- <attribute name="BreachScript">gcThresholdBreach.groovy</attribute> -->
  </mbean>
</server>
			

A Gateway Recovery configuration is used to match Gateways to Threshold configurations based upon criteria defined in the configuration. The Threshold configuration matched to a Gateway then contains instances of Restart configurations that are applied to a FAILED Gateway. The following Gateway attributes can be used to match FAILED Gateways to Gateway Recovery configurations: GatewayName, GatewayManager, GatewayManagerClass, and GatewaySystem. These four attributes can take values that are literal or regular expressions. The regular expressions follow the same rules as the Gateway Table mask pattern in the Gateway Central client.

More than one Threshold configuration can be associated with a Gateway Recovery configuration. When a Threshold is breached, the next Threshold becomes active. When the last Threshold is reached, it is simply recycled until the Gateway failure is cleaned up from AGM.

The algorithm used to match FAILED Gateways to Gateway Recovery configurations is best-match. Each configuration is compared against the FAILED Gateway, and the configuration that has the highest number of matching attributes to the Gateway becomes the configuration associated with the FAILED Gateway. FAILED Gateways are matched against the GatewayRecovery configurations in the order that they appear in this configuration file. If more than one configuration has the same number of matching attributes, the configuration that first matched that number of attributes becomes associated with the FAILED Gateway. If all configurations match zero attributes, the first configuration in the list will become associated with the FAILED Gateway. Therefore, a user could specify a default that only contains a Threshold configuration set with no other attributes, and put it first in the list. That way, if no other configurations match, that configuration will become the default.

Following is a list of the attributes in a Gateway Recovery configuration along with a description of each attribute:

Following is a sample Gateway Recovery configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<server>
  <mbean code="com.lsft.nx.agm.config.GatewayRecovery" 
         name="LongviewServer.Service.AGM:recovery=DefaultGatewayRecovery">
  	<attribute name="GatewayManagerClass">Cisco.*</attribute>
  	<attribute name="ThresholdConfigurations">
  		<thresholds>
  			<threshold>LongviewServer.Service.AGM:
	threshold=DefaultThreshold</threshold>
  		</thresholds>
  	</attribute>
  </mbean>
</server>
			

An example of using a specific class on a schedule is the Failed Gateway Cleanup service. This service is responsible for cleaning up old FailedGateway instances, meaning FailedGateway instances that have not exceeded their Threshold during the Threshold period.

Following is the confguration for the Failed Gateway Cleanup service, which is specified in 02-lsft-gcAGM-Scheduler-service.xml:

<mbean code="com.lsft.nx.agm.service.FailedGatewayCleanup" 
       name="LongviewServer.Schedulable.AGM:name=FailedGatewayCleanup">
</mbean>
<mbean code="org.jboss.varia.scheduler.Scheduler" 
       name="LongviewServer.Service.AGM:service=Scheduler,name=FailedGatewayCleanup">
  <attribute name="StartAtStartup">true</attribute>
  <attribute name="SchedulableMBean">LongviewServer.Schedulable.AGM:
	name=FailedGatewayCleanup</attribute>
  <attribute name="SchedulableMBeanMethod">runProcess()</attribute>
  <attribute name="InitialStartDate">NOW</attribute>
  <attribute name="SchedulePeriod">600000</attribute> <!-- 10 minutes -->
  <attribute name="InitialRepetitions">-1</attribute>
  <depends>LongviewServer.Service.AGM:service=FailedGatewayMonitor</depends>
</mbean>
			

A scheduled service consists of two distinct parts, the Schedulable MBean and the Scheduler MBean instance. The Schedulable MBean specifies the class and name of the service that is to be run. This is specified above by the following lines:

<mbean code="com.lsft.nx.agm.service.FailedGatewayCleanup" 
       name="LongviewServer.Schedulable.AGM:name=FailedGatewayCleanup">
</mbean>
			

The Scheduler MBean instance specifies the schedule on which the Schedulable MBean is run. This is specified above by the following lines:

<mbean code="org.jboss.varia.scheduler.Scheduler" 
       name="LongviewServer.Service.AGM:service=Scheduler,name=FailedGatewayCleanup">
  <attribute name="StartAtStartup">true</attribute>
  <attribute name="SchedulableMBean">LongviewServer.Schedulable.AGM:
	name=FailedGatewayCleanup</attribute>
  <attribute name="SchedulableMBeanMethod">runProcess()</attribute>
  <attribute name="InitialStartDate">NOW</attribute>
  <attribute name="SchedulePeriod">600000</attribute> <!-- 10 minutes -->
  <attribute name="InitialRepetitions">-1</attribute>
  <depends>LongviewServer.Service.AGM:service=FailedGatewayMonitor</depends>
</mbean>
			

The MBean code attribute value for a Scheduler is always org.jboss.varia.scheduler.Scheduler, and the user can provide any name they wish, however, it should always begin with LongviewServer.Service.AGM:service=Scheduler.

Following is a list of the attributes that define a Scheduler instance:

To use the generic script Schedulable MBean, the scheduler part is the same as above, but the Schedulable MBean portion is different. Following is a full example of using the script Schedulable MBean:

<mbean code="com.lsft.nx.agm.schedule.GatewayCentralScriptSchedulable" 
       name="LongviewServer.Schedulable.AGM:name=GCSchedulableMBeanExample">
	<attribute name="ScriptName">hello.groovy</attribute>
</mbean>
<mbean code="org.jboss.varia.scheduler.Scheduler" 
       name="LongviewServer.Service.AGM:service=Scheduler,name=GCSchedulableMBeanExample">
  <attribute name="StartAtStartup">false</attribute>
  <attribute name="SchedulableMBean">LongviewServer.Schedulable.AGM:
	name=GCSchedulableMBeanExample</attribute>
  <attribute name="SchedulableMBeanMethod">runProcess()</attribute>
  <attribute name="InitialStartDate">NOW</attribute>
  <attribute name="SchedulePeriod">10000</attribute>
  <attribute name="InitialRepetitions">10</attribute>
</mbean>
			

The code attribute of the Schedulable MBean is always com.lsft.nx.agm.schedule.GatewayCentralScriptSchedulable , and the user can provide any name they wish. The only attribute defined in a script Schedulable instance is ScriptName, which specifies the Groovy script to be run on the defined schedule.

Currently, configuring the scripting engine consists solely of optionally specifying a set of paths where scripts may reside. The distribution contains a configuration file named lsft-gcAGM-properties-service.xml, which contains a single Java System property named lsft.agm.script.paths. The acceptable value for this property is a comma-delimited list of absolute file system paths where AGM scripts reside. The default value is blank. If the property is left blank or is removed, the scripting engine is configured to only look for scripts in the $GC_SERVER_HOME/script directory.

This section covers the objects that are embedded to the scripts that are executed for each service. Regardless of the service however, all scripts receive a copy of the Gateway Central EJB interfaces. Following is the list of EJB interfaces embedded into all scripts.

Following is the list of script types and the set of objects that are embedded into each in addition to the EJB interfaces mentioned above.

The agm-lib directory contains two jar files. The main AGM library is lsft-AutomatedGatewayManagement.jar. The director also contains groovy-all-1.0.jar in the event that the server does not contain the jar file already. To install the libraries, simply copy them to GC_SERVER_HOME/server/lsft/lib. Again, the groovy jar needs only be copied if the file does not already exist in the server lib directory.

As stated above, the agm-scripts directory contains the default scripts referenced by the Failed Gateway Monitor and Inactive Gateway Monitor. These scripts need to be edited (if necessary) and copied to the GC_SERVER_HOME/script directory or any directory referenced by the scripts path configured in the scripting engine as described in Section 5.1, “Configuring the Scripting Engine”.

AGM leverages the power of JBoss’ MBean implementation by creating all configurations as MBean instances. An MBean is a Management Bean and can be viewed and edited via the JMX Console (see Appendix A, JMX Console). There are benefits and drawbacks to using this approach. One drawback is that the configuration file scheme may be more difficult to read and decipher than if it were a custom scheme. However, by looking at the example configurations, the format should be easy to learn. One bonus of this configuration scheme is that no custom configuration parser had to be written. The JBoss server reads the files and handles the object deployments automatically. All configuration files should be placed in a user-created agm-config subdirectory under the server’s deploy directory unless otherwise noted.

The agm-config directory in the AGM tar file contains default configuration files. The configuration files can be edited in the staging area and then entire agm-config directory can be copied to GC_SERVER_HOME/server/lsft/deploy. The server can pick up the configurations while in a sub-directory of the server's deploy directory, and this will help keep the configurations organized. Note that along with the default scripts mentioned above, the default configurations can be used as-is to get up and running quickly with AGM. Using the default configurations will cause all Gateways to be treated the same, and there will be no breach scripts. Following is a brief list of the files contained in the agm-config directory and what each file does.