.. highlight:: xml
.. index:: Miscellaneous Tasks

.. _misc_tasks:

Miscellaneous Tasks/Commands
============================

.. _action:

``action``
----------

This task allows you to extend DPBuddy with various DataPower administration functions which are not implemented by other DPBuddy tasks.

A complete list of available actions can be found in the xml-mgmt.xsd file, under the type "AnyActionElement". Documentation for actions can be found in the `DataPower command reference documentation <http://pic.dhe.ibm.com/infocenter/wsdatap/v5r0m0/index.jsp?topic=%2Fcom.ibm.dp.xi.doc%2Fcommandreference.xi5041.htm&path%3D4_4_0_3>`_ under "Global mode" and "Initial login and common commands". Note that many actions can be executed using other DPBuddy tasks. For example, DPBuddy provides dedicated tasks for flushing caches, so there is no need to know how to do it using "action".

To execute actions/commands without parameters, simply provide the action's name using the ``name`` attribute of the ``action`` task.

For example, the SOMA counterpart for `"save error-report" <http://pic.dhe.ibm.com/infocenter/wsdatap/v5r0m0/index.jsp?topic=%2Fcom.ibm.dp.xg.doc%2Fcommandreference.xg45171.htm&path%3D3_4_0_3_129>`_ command is "ErrorReport" action. This action can be executed as follows:

.. code-block:: xml

   <dp:action name="ErrorReport" />

Most actions, however, take some parameters. For these actions you need to provide a nested XML fragment with all the necessary XML elements for the action. The XML fragment can be nested directly inside the ``action`` task.

Attributes/Options
^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Name
     - Description
     - Required
   * - name
     - Name of SOMA action as per the DataPower XML schema.
     - No
   * - rollbackOnError
     - If set to ``true``, roll back the domain's configuration to the last checkpoint (if it exists), in case of any errors.

       Defaults to ``false``.
     - No

Examples
^^^^^^^^

The "ping" action (see `ping command documentation <http://pic.dhe.ibm.com/infocenter/wsdatap/v5r0m0/index.jsp?topic=%2Fcom.ibm.dp.xg.doc%2Fcommandreference.xg4530.htm&path%3D3_4_0_2_20>`_) requires "RemoteHost" as a parameter.

"ping" invocation could be encoded using the following XML fragment:

.. code-block:: xml

   <dp:action>
       <Ping>
           <RemoteHost>${ping.host}</RemoteHost>
       </Ping>
   </dp:action>

You can find more examples under ``samples`` in your distribution or `online <http://myarch.com/dpbuddy-examples/>`_.

.. _exec:

``exec``
--------

The ``exec`` task executes a DataPower configuration script. The configuration script contains `DataPower CLI commands <http://www.ibm.com/support/knowledgecenter/SS9H2Y_7.5.0/com.ibm.dp.doc/readingsyntaxstatements.html>`_. This task performs the same function as the `exec DataPower command <http://www.ibm.com/support/knowledgecenter/SS9H2Y_7.5.0/com.ibm.dp.doc/exec_common.html>`_.

Before executing the script on the device, the ``exec`` task uploads the script file to the device.

As with all other DPBuddy tasks, ``exec`` does not use SSH, it relies on XML management interface (SOMA) instead.

Note that scripts will be automatically executed in the global configuration mode. Therefore, don't use "configure terminal" in your scripts. Also, scripts are not allowed to exit the global configuration mode, therefore the "top" command is not allowed.

You can use variables/properties anywhere inside the configuration script. DPBuddy will attempt to resolve the properties before uploading the file. If any of the properties remains unresolved, the task will fail.

Instead of a script, you can provide a single command (or semicolon-delimited list of commands) to ``exec``. In this case, DPBuddy will create the script "commands.cfg" containing the provided commands on the device and execute it.

Note that ``exec`` cannot capture the output of the commands specified in the configuration script, e.g., if you have an "echo" command in the script, the output of "echo" will not be returned to DPBuddy. So, if the script execution fails, you will need to login to the device and re-execute the script (which would already be pre-uploaded by DPBuddy) using the "exec" DataPower command.

Attributes/Options
^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Name
     - Description
     - Required
   * - file
     - Path to the configuration script file, including file extension.
     - Yes, unless ``command`` was provided.
   * - | command
       | CLI alias: ``-cmd``
     - A single command or a semicolon-delimited list of commands to execute on the device.
     - Yes, unless ``file`` was provided.
   * - toDir
     - Specifies the target directory for uploaded configuration scripts on the device. It could include a filesystem which is defined using ``filesystem:/`` syntax. If not provided, the filesystem will default to ``local:/``. If the directory does not exist, it will be created.

       Defaults to ``local:/cfg-scripts``.
     - No
   * - scriptName
     - The name of the script file on the device.

       If ``file`` was provided, defaults to the local name of that file. If ``command`` was provided, defaults to "commands.cfg"
     - No
   * - resolveVars
     - If set to ``true``, attempt to resolve variables (${}) inside the configuration script file. DPBuddy will raise an exception if any variables/properties remain unresolved.

       Defaults to ``true``.
     - No
   * - rollbackOnError
     - If set to ``true``, roll back the domain's configuration to the last checkpoint (if it exists), in case of any errors.

       Defaults to ``false``.
     - No

Examples
^^^^^^^^

.. code-block:: bat

   dpbuddy exec -file dpconfigs/ping-dpcli.cfg
   dpbuddy exec -cmd "ping 127.0.0.1"

.. code-block:: xml

   <dp:exec file="${dpconfig.home}/ping-dpcli.cfg"/>


.. _exportConf:

``exportConf``
--------------

``exportConf`` allows developing shell scripts that use values from the DPBuddy conf file.
This command generates a file (by default, in shell/bash format) containing :ref:`DPBuddy configuration <hoconConfig>`  for a given device/environment. Shell scripts can then source this file and use the variables.
Each configuration path is translated into a variable with the same name, with dots replaced by underscores.
E.g.,

.. code-block:: bat

  dp.status.ignore.objects: "ISAMRuntime:isam-runtime"

Is translated into:

.. code-block:: bat

  export dp_status_ignore_objects="ISAMRuntime:isam-runtime"

Options
^^^^^^^

.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Name
     - Description
     - Required
   * - | outFile
       | CLI alias: ``-file``
     - Output file containing shell variables generated based on the current DPBuddy configuration (must be defined using HOCON format).
     - Yes
   * - template
     - Template for each variable (line). Must contain two '%s' (Java format). The first '%s' is the name of the variable, the second '%s' is the value from the config file.
       Defaults to ``export %s=\"%s\"``.
     - No

Examples
^^^^^^^^

.. code-block:: bat

   dpbuddy exportConf -outFile conf_export.sh -env dev


.. _firmware:

``firmware``
------------

The ``firmware`` command copies a firmware image to DataPower, installs it and reboots the device from the new image. The image can be copied from any external or internal website over HTTP/HTTPS. Internally, DPBuddy uses `DataPower copy CLI command <http://www.ibm.com/support/knowledgecenter/SS9H2Y_7.5.0/com.ibm.dp.doc/copy_flash.html>`_ to copy the image.

You can copy the firmware image directly from the IBM Fix Central website. Login to Fix Central, locate the firmware file that you need, accept the license and save the download link. Use this link as the value for the ``fromUrl`` parameter.

By default, DPBuddy will wait for the reboot to complete. It will then print the version of the firmware reported by DataPower after the reboot.

Attributes/Options
^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Name
     - Description
     - Required
   * - fromUrl
     - http or https URL of the firmware image. This URL will be used by the DataPower "copy" command that runs directly on the device. If not provided, DPBuddy assumes that the firmware image file was already copied to DataPower at the location specified by ``dpFile``.
     - No
   * - dpFile
     - Absolute path to the image file on DataPower. If not provided, the name will be inferred from ``fromUrl``. The DataPower filestore defaults to 'image://'.
     - No
   * - timeout
     - Time, in seconds, to wait for DataPower to become available after applying the firmware image. -1 disables waiting.

       Defaults to 300 seconds.
     - No
   * - xmlManager
     - Name of the XML manager to use for copying from https URLs. If not provided, DPBuddy will automatically create the XML Manager and other required objects (user agent, crypto profile) required to support TLS/SSL. All object names start with 'dpbuddy-copy'. The "default" XML manager in DataPower does not support TLS out of the box, so this configuration is required, unless the "default" manager or a custom manager was already updated to support TLS.
     - No


Examples
^^^^^^^^
Copy the 7.5.2.1 image directly from IBM Fix Central, apply it and wait for the completion of the reboot:

.. code-block:: bash

  dpbuddy firmware -fromUrl "https://delivery04.dhe.ibm.com/sar/CMA/WSA/06l8h/0/xi7521.scrypt4"


Apply the image previously uploaded to "image://", don't wait for the reboot:

.. code-block:: bash

  dpbuddy firmware -dpFile "xi7521.scrypt4" -timeout -1

Copy the 7.5.2.1 image directly from IBM Fix Central, apply it and wait for the completion of the reboot. Use existing XML Manager with SSL profile.

.. code-block:: bash

  dpbuddy firmware -fromUrl "https://delivery04.dhe.ibm.com/sar/CMA/WSA/06l8h/0/xi7521.scrypt4" -xmlManager "xmlManagerWithSsl"

.. _license:

``license``
-----------

This task/command prints the DPBuddy's license information, including the expiration date and appliance entitlements.

Examples
^^^^^^^^

.. code-block:: bat

   dpbuddy license

.. _passwordAliasTask:

``passwordAlias``
--------------------

This task creates `password alias <http://www.ibm.com/support/knowledgecenter/SS9H2Y_7.5.0/com.ibm.dp.doc/passwordmap.html?lang=en>`_. The password is securely stored on the device and DataPower configuration objects can reference the alias instead of specifying the password directly,

If the password is encrypted, DPBuddy will attempt to :ref:`decrypt <encrypting_props>` it automatically.

If the alias with this name already exists, DPBuddy will override it with the new password (the existing alias object is deleted first).

Attributes/Options
^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Name
     - Description
     - Required
   * - name
     - Name of the alias
     - Yes
   * - passwd
     - Password. It is recommended to encrypt the password using :ref:`DPBuddy encryption support <encrypting_props>`.
     - Yes

Examples
^^^^^^^^
.. code-block:: xml

  <dp:passwordAlias name="test-alias" passwd="ENC{NIR5xVHWngkGpsBA/Y9YT4KTDtgAPiBN}" />

.. code-block:: bat

  dpbuddy passwordAlias -name test-alias -passwd "ENC{NIR5xVHWngkGpsBA/Y9YT4KTDtgAPiBN}"

.. _pingTask:

``ping``
--------

This task executes "ping" on the device against the provided host name.

Attributes/Options
^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Name
     - Description
     - Required
   * - | remoteHost
       | CLI alias: ``-rh``
     - Host or IP to ping from DataPower
     - Yes

Examples
^^^^^^^^

.. code-block:: bat

   dpbuddy -rh 127.0.0.1


.. _restartDP:

``restartDP``
-------------

This task/command restarts the appliances and optionally waits for the completion of the restart process.

Attributes/Options
^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Name
     - Description
     - Required
   * - timeout
     - Time, in seconds, to wait for DataPower to become available after restart. -1 disables waiting.

       Defaults to 240 seconds.
     - No
   * - mode
     - Restart mode: reload, reboot or halt.

       Defaults to ``reload``.
     - No
   * - quiesce
     - Quiesce all the domains before performing the restart.

       Defaults to ``false``.
     - No



Examples
^^^^^^^^

.. code-block:: bat

  dpbuddy restartDP -mode reboot

.. code-block:: xml

  <dp:restartDP mode="reboot" />


.. _somaRequest:

``somaRequest``
---------------

The ``somaRequest`` task  executes an arbitrary SOMA request defined in an external file.

Do not specify SOAP envelope XML elements in the file; DPBuddy will add them automatically.

You can use Ant variables in any text node or in any attribute of the XML file.

This task will attempt to validate XML request against DataPower schema unless the ``validate`` attribute is set to ``false``.

Attributes/Options
^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Name
     - Description
     - Required
   * - file
     - SOMA request file.
     - Yes
   * - printResponse
     - If set to ``true``, print XML response from the device. The SOAP envelope is stripped out and not printed.

       Defaults to ``false``.
     - No
   * - rollbackOnError
     - If set to ``true``, roll back the domain's configuration to the last checkpoint (if it exists), in case of any errors.

       Defaults to ``false``.
     - No

Examples
^^^^^^^^

.. code-block:: bat

  dpbuddy somaRequest -printResponse -file dpconfigs/ping-remote-host.xml

.. code-block:: xml

  <dp:somaRequest file="ping-remote-host.xml" />

Here is the content of "ping-remote-host.xml":

.. code-block:: xml

   <?xml version="1.0" encoding="UTF-8"?>
   <dp:request xmlns:dp="http://www.datapower.com/schemas/management" >
       <dp:do-action>
           <Ping>
               <RemoteHost>${ping.host}</RemoteHost>
           </Ping>
       </dp:do-action>
   </dp:request>

.. _testConnection:

``testConnection``/``connect``
------------------------------

This task accesses the device and retrieves and prints its firmware version. This task could be used to test connectivity with DataPower. The task does not have any task-specific attributes/options.


Examples
^^^^^^^^

.. code-block:: bat

   dpbuddy connect



.. _wsrrSynch:

``wsrrSynchronize``
-------------------

This task synchronizesWSRR content with the WSRR server. See `wsrr-synchronize command documentation <http://pic.dhe.ibm.com/infocenter/wsdatap/v6r0m1/index.jsp?topic=%2Fcom.ibm.dp.xi.doc%2Fwsrr-synchronize_global.html&resultof%3D%2522%2577%2573%2572%2572%252d%2573%2579%256e%2563%2568%2572%256f%256e%2569%257a%2565%2522%2520>`_ for more details.

Attributes/Options
^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Name
     - Description
     - Required
   * - subscription
     - Specifies the name of a WSRR subscription or a WSRR Saved Search subscription object. Content previously retrieved using this subscription is immediately synchronized with the WSRR server specified by the subscription.
     - Yes

Examples
^^^^^^^^

.. code-block:: xml

   <dp:wsrrSynchronize subscription="testSubscription" />