.. highlight:: xml .. index:: Checking Status .. _status_checking_tasks: Monitoring/Verification Commands ================================ .. _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-runtime, APIConnectGatewayService:apic-gw-service" 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 * - | 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. .. 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 ``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 ^^^^^^^^^^^^^^^^^^ .. 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:: bash dpbuddy assertOpenPorts -ports="9090, 5550" -domain default .. code-block:: xml .. _testTcp: ``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 ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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 ^^^^^^^^ .. code-block:: bash dpbuddy testTcp -hostPort "google.com:443, google.com:80"