25. Miscellaneous Tasks/Commands

25.1. 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 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” command is “ErrorReport” action. This action can be executed as follows:

<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.

25.1.1. Attributes/Options

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

25.1.2. Examples

The “ping” action (see ping command documentation) requires “RemoteHost” as a parameter.

“ping” invocation could be encoded using the following XML fragment:

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

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

25.2. exec

The exec task executes a DataPower configuration script. The configuration script contains DataPower CLI commands. This task performs the same function as the exec DataPower command.

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.

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.

25.2.1. Attributes/Options

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

25.2.2. Examples

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

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

25.3. license

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

25.3.1. Examples

dpbuddy license

25.4. passwordAlias

This task creates password alias. 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 decrypt 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).

25.4.1. Attributes/Options

Name Description Required
name Name of the alias Yes
passwd Password. It is recommended to encrypt the password using DPBuddy encryption support. Yes

25.4.2. Examples

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

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

25.5. ping

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

25.5.1. Attributes/Options

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

25.5.2. Examples

dpbuddy -rh 127.0.0.1

25.6. restartDP

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

25.6.1. Attributes/Options

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

25.6.2. Examples

dpbuddy restartDP -mode reboot

<dp:restartDP mode="reboot" />

25.7. 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.

25.7.1. Attributes/Options

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

25.7.2. Examples

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

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

Here is the content of “ping-remote-host.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>

25.8. testConnection

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.

25.8.1. Examples

dpbuddy testConnection

25.9. wsrrSynchronize

This task synchronizesWSRR content with the WSRR server. See wsrr-synchronize command documentation for more details.

25.9.1. Attributes/Options

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

25.9.2. Examples

<dp:wsrrSynchronize subscription="testSubscription" />