.. highlight:: xml .. index:: Checking Status .. _status_tasks: Tasks/Commands for Checking DataPower Status ============================================ .. _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 :ref:`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 ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - Name - Description - Required * - class - Status ``class`` as defined in xml-mgmt.xsd. - Yes Examples ^^^^^^^^ .. code-block:: bat dpbuddy status -class MemoryStatus .. code-block:: xml .. _serviceStatus: ``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 ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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 ^^^^^^^^ .. code-block:: bat dpbuddy serviceStatus -domainPatterns ".*" .. code-block:: xml .. _assertStatus: ``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, ```` will print a line similar to this: .. code-block:: bat 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 ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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 ^^^^^^^^ .. code-block:: bat dpbuddy assertStatus -class="LoadBalancerStatus2" -expression="(Group!='test-group' || Health=='up')" .. code-block:: xml .. _free_space: ``assertFreeSpace`` ------------------- ``assertFreeSpace`` is a convenience task, which checks that there is enough free disk space on the device. Internally, the task utilizes :ref:`assertStatus` task described earlier. Attributes/Options ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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 ^^^^^^^^ .. code-block:: xml You can find more examples under ``samples`` in your distribution or `online `_. .. _assertState: ``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 :ref:`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: .. code-block:: bat dp.status.ignore.objects=ISAMRuntime:isam.*, PasswordMap:password-alias-map Attributes/Options ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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 :ref:`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. .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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: .. code-block:: bat dpbuddy assertState -objects "WSGateway, XMLF.*" -activeService .. code-block:: xml .. _assertActiveService: ``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 ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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. .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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: .. code-block:: xml .. _assertOpenPorts: ``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 :ref:`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 ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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: .. code-block:: bat dpbuddy assertOpenPorts -ports="9090, 5550" -domain default .. code-block:: xml