Tasks/Commands for Checking DataPower Status

status

The status task retrieves the status of various parameters of a device and prints it to standard out. The status is displayed in the form “name: value”, where “name” is the name of the parameter.

DataPower groups status parameters into “classes” (not to be confused with the classes of DataPower objects). Each status class is responsible for a certain characteristic of the device, such as memory, CPU utilization and so on.

A complete list of status classes can be found under the “StatusEnum” type in xml-mgmt.xsd.

The most useful classes include “MemoryStatus” and “FilesystemStatus”. These classes give information about available RAM and disk space. “ObjectStatus” can be used to find out the status of all DataPower objects.

Attributes/Options

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

Examples

dpbuddy status -class MemoryStatus

<dp:status class="ObjectStatus" />
<dp:status class="MemoryStatus" />
<dp:status class="FilesystemStatus" />

serviceStatus

serviceStatus prints the list of active services and their port numbers. This is the same information that is available from WebGUI under “Status”/”Main”/”Active Services”.

serviceStatus is also capable of querying multiple domains and providing information about services running in each domain.

Attributes/Options

Name Description Required
domainPatterns

Comma-delimited list of regular expression patterns defining which domains to query.

To query all domains use ”.*”

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

 No

Examples

dpbuddy serviceStatus -domainPatterns ".*"

<dp:serviceStatus domainPatterns=".*"/>

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.*, PasswordMap:password-alias-map

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

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 nested object elements 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 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" />