Monitoring/Verification Commands

assertStatus

assertStatus can be used to validate (“assert”) the status of various DataPower objects. The status task documented above simply reports the status. assertStatus raises an exception when some parameters don’t meet the expectations.

For example, you may want to check that there is enough free memory (RAM) on the device before performing a deployment/import. You can run assertStatus and check that the “FreeMemory” parameter of the “MemoryStatus” class is above a certain threshold.

The condition for the assertion is defined using a Groovy Boolean expression. In this expression, you can also refer to any of the parameters of the returned status as Groovy variables. For example, “FreeMemory” is one of the parameters returned in response to querying “MemoryStatus”. Your Groovy expression can simply compare the MemoryStatus variable to a certain memory threshold: FreeMemory >= ${dataPowerMemoryThreshold}.

Run assertStatus with expression set to true first to find out which parameters are returned for each status class. For example, <dp:assertStatus class="MemoryStatus" expression="true"/> will print a line similar to this:

Usage: 25, TotalMemory: 3368389, UsedMemory: 870929, FreeMemory: 2497460, ReqMemory: 903824, HoldMemory: 32895, ReservedMemory: 689911, InstalledMemory: 4058300

Your Groovy expression can reference any of the names in this output as variables.

Attributes/Options

Name Description Required
class Status “class” as defined in xml-mgmt.xsd. Yes
expression

A Groovy Boolean expression (has to return true or false). All parameters returned in response to querying the status class are also available as Groovy variables.

In addition to this, there is a special dp variable containing the following properties: url, username, and domain. These properties are populated with the values for the device/domain against which the task is being executed.

If the expression returns false, the task will raise an exception.

 Yes

Examples

dpbuddy assertStatus -class="LoadBalancerStatus2" -expression="(Group!='test-group' || Health=='up')"

<property name="dpMemoryThreshold" value="3000000"/>
<dp:assertStatus class="MemoryStatus" expression="FreeMemory&gt;=${dpMemoryThreshold}"/>

assertFreeSpace

assertFreeSpace is a convenience task, which checks that there is enough free disk space on the device. Internally, the task utilizes assertStatus task described earlier.

Attributes/Options

Name Description Required
minFreeSpace Minimally acceptable free disk space in MB. The task will raise an exception if the free space is below this value. Yes

Examples

<dp:assertFreeSpace minFreeSpace="15000" />

You can find more examples under samples in your distribution or online.

assertState

assertState checks the operational state of DataPower objects. The task raises an exception if at least one object is not in the desired state (“up” or “down”). The task excludes disabled objects from the check.

For every object in the “down” state, the task will retrieve and display the five most recent log entries for that object, to facilitate troubleshooting.

The task should be run after import to ensure that all objects involved in the import operation were created/updated successfully. It is possible for an import operation to succeed while leaving objects/services in the “down” state.

assertState supports a global “ignore” list of objects that should always be excluded from the state check. The list is specified using the property dp.status.ignore.objects. This property can contain a comma-delimited list of “class:object” patterns, where “class” is a regexp pattern matching one of the DataPower classes and “object” is a regexp pattern matching names of DataPower objects, for example:

dp.status.ignore.objects="ISAMRuntime:isam-runtime, APIConnectGatewayService:apic-gw-service"

Attributes/Options

Name Description Required
objects Comma-delimited list of regexp patterns to check in the format “class:name, class:name”. Class and name could be optional, e.g., “class, class” or “:name”. No
exclude Comma-delimited list of regexp patterns to exclude from the check in the format “class:name, class:name”. No
classPattern
CLI alias: class
 Regular expression defining which classes (types) to check. Deprecated, use “objects” instead. No
namePattern
CLI alias: name
 Regular expression defining object names to check. Deprecated, use “objects” instead. No
state

Operational state to check. Allowed values are “up” or “down”. An error is raised if at least one object is not in this state.

Defaults to “up”.

 No
activeService

If set to true, invoke assertActiveService to check that all objects defined using nested object elements are present in the active services list.

Defaults to false.

 No
domainPatterns
CLI alias: domains

Comma-delimited list of regular expression patterns defining what domains to apply the command to. Use ‘.*’ for all domains except the default. Use ‘.*,default’ to include the default domain.

Defaults to the current domain. The current domain is specified using the dpDomain property or domain attribute of the task.

 No

object Nested Element

Each object element must match at least one DataPower configuration object.

Attribute Description Required
class Regular expression defining what classes (types) to check. Yes, unless name was provided.
name Regular expression defining object names to check. Yes, unless class was provided.

Examples

Verify that all Web services proxies and XML firewalls are “up” and listening for requests:

dpbuddy assertState -objects "WSGateway, XMLF.*" -activeService

<dp:assertState state="up" activeService="true">
    <object class="(WSGateway|XMLFi.*)" />
</dp:assertState>

assertActiveService

assertActiveService checks if the services defined using objects are, in fact, running and listening for requests. It is possible for a service, such as a Web services proxy, to be in the up operational state (and pass the assertState check) while still not running/accepting requests. All objects specified using objects option/attribute have to be listed in the active services list returned by the serviceStatus task (this list can also be obtained from Status/Main/Active Services in WebGUI).

The task also prints the list of active services and their ports.

Attributes/Options

Name Description Required
objects Comma-delimited list of regexp patterns to check in the format “class:name, class:name”. Class and name could be optional, e.g., “class, class” or “:name”. Yes
exclude Comma-delimited list of regexp patterns to exclude from the check in the format “class:name, class:name”. No

object Nested Element

Each object element must match at least one DataPower configuration object.

Name Description Required
class Regular expression defining what classes (types) to check. Yes, unless name was provided.
name Regular expression defining object names to check. Yes, unless class was provided.

Examples

Verify that all Web services proxies and XML firewalls are listening for requests:

<dp:assertActiveService>
    <object class="(WSGateway|XMLFi.*)" />
</dp:assertActiveService>

assertOpenPorts

assertOpenPorts checks if the ports specified using the ports attribute are assigned to active services. Note that this task does not attempt to actually open the ports; instead it obtains the list of active services from the device using the listServices/serviceStatus task and checks that all the provided ports are in that list. The task will raise an exception if this is not the case.

The task also prints the list of active services and their ports.

Attributes/Options

Name Description Required
ports A comma-delimited list of ports to check. Yes

Examples

Verify that the default WebGUI and XML management ports are open:

dpbuddy assertOpenPorts -ports="9090, 5550" -domain default

<dp:assertOpenPorts ports="9090, 5550" domain="default" />

testTcp

This commands executes tests if a host/port is reachable from DataPower. It is equivalent to the functionality available from WebGUI.

Use this task to verify connectivity from DataPower to your back-end services.

The command fails a host/port is not reachable, so it can be used for monitoring connectivity to other components from “inside” DataPower.

Attributes/Options

Name Description Required
hostPort
CLI alias: -rh
 List of comma-delimited host:port, e.g., my.backend.com:443,192.168.1.12:8080. Port 443 is the default. Yes

Examples

dpbuddy testTcp -hostPort "google.com:443, google.com:80"