2. DPBuddy Installation and Configuration

2.1. DPBuddy Installation

DPBuddy requires Java SE Runtime Environment 7 or better. All JVM types are supported, including Oracle, IBM and OpenJDK. DPBuddy is pure Java, so it runs on any OS where Java is available. In some cases, DPBuddy may require a large heap size so a 64-bit JRE is recommended.

Make sure to use an up-to-date version of Java; for JDK/JRE 7, update 79 is recommended to avoid SSL-related errors when trying to connect to DataPower.

Both DPBuddy and Apache Ant will first check if the JAVA_HOME environment variable is defined. If it is defined, this Java installation will be used. If JAVA_HOME is not defined, then java executable must be added to the path. To verify, run the java -version command.

Install DPBuddy by following these simple steps:

  • Download the distribution from myarch.com and unzip/untar the content of the file into a directory (tar -xvf on Linux).
  • Define the DPBUDDY_HOME environment variable and point it to the directory containing DPBuddy installation, e.g., /home/dpbuddy/dpbuddy-3.2 or c:\dpbuddy\dpbuddy-3.2.
  • Add %DPBUDDY_HOME%\bin or $DPBUDDY_HOME/bin to your PATH environment variable.
  • Open a command line/terminal window and type dpbuddy -h. You should see a help screen containing the list of commands supported by the tool.

If you already have a previous version of DPBuddy installed, you will need to update your taskdef Ant tag to point to the location of the new version.

DPBuddy does not require root or administrator privileges, it can run under a “regular” user account.

When running DPBuddy under a non-administrative account on Windows you may see the warning “Could not open/create prefs root node SoftwareJavaSoftPrefs ...”. This warning can be ignored. This can also be fixed by running DPBuddy as administrator once (after that you can continue running it as user) or by manually creating necessary keys in the Windows registry as explained here.

2.2. Upgrading DPBuddy

To upgrade DPBuddy, simply un-archive the distribution into a new folder and change your DPBUDDY_HOME environment variable to point to the new location.

The DPBuddy 3.2 distribution contains Apache Ant 1.9 jar files. To avoid classloader conflicts, exclude Ant jars from the taskdef used to define DPBuddy tasks. Additionally, DPBuddy 3.2.4 uses logback logging framework and relies on logback.xml configuration file. “logback.xml” is located in “$DPBUDDY_HOME/conf” directory. In Ant, this directory needs to be explicitly added to the classpath of the DPBuddy’s “taskdef”. The resulting “taskdef” should be defined as following:

<taskdef uri="antlib:com.myarch.dpbuddy">
    <classpath>
        <pathelement location="${dpbuddy.home}/conf"/>
        <fileset dir="${dpbuddy.home}/lib" excludes="ant-*"/>
    </classpath>
</taskdef>

All DPBuddy 3.2 tasks are backward compatible with 3.0 and 3.1.

2.3. Upgrading from DPBuddy 2.3

DPBuddy 3 is mostly backward compatible with DPBuddy 2.3 with a few exceptions:

  • The namespace for the DPBuddy antlib has changed to com.myarch.dpbuddy. Make sure to update it in the project tag and in the taskdef of your build file, e.g., xmlns:dp="antlib:com.myarch.dpbuddy".
  • The request task was renamed to somaRequest.
  • The setConfig task was deprecated; use import instead.
  • modifyConfig no longer supports the nested configFile element. You can replace it with the new transform element.
  • toDir is now a required attribute of the copy. You can also provide toDir at the nested dpFileset level.
  • Environment prefix mechanism has been substantially enhanced; you may need to change the way your properties are named to take advantage of the hierarchical prefixes.

2.4. Configuring DataPower to Work with DPBuddy

You need to make sure that you have XML Management enabled in all devices that will be managed by DPBuddy. You can do this from DataPower WebGUI (Network/Management/XML Management).

DPBuddy does not use SSH, so SSH can be disabled.

DPBuddy uses the “old” DataPower v2004 message format for file transfer (the 2004 schema is more efficient, since it allows for uploading multiple files at once). This means that the “SOAP Configuration Management (v2004)” checkbox must be checked on the XML management screen.

Be careful performing these changes on the appliances residing in a production DMZ – make sure that the management ports are not available to the outside world.

We also recommend enabling internal logging as documented in the DataPower Info Center. DataPower does not return error messages to the client. If a DPBuddy command fails and you get an “Internal Error” message from the device, you will need to look for the root cause in the DataPower system log in the default domain. DataPower captures the error only if internal logging is enabled. You can enable it by navigating to “Troubleshooting” from the control panel, then to “Logging.” Set “Enable Internal Logging” and click on “Set Log Level.” We recommend setting the level to “Warning”, since anything more detailed (e.g., “Information”) results in needlessly verbose messages.

If you’re creating a new account that will be used by DPBuddy, make sure that the password for the account has been reset. Before running DPBuddy, make sure that you’re able to login to WebGUI using this account.

DPBuddy will work with any “Group-Defined” account that has read/write access to the target domain(s). In general, DPBuddy does not need to access the “default” domain. However, certain features of DPBuddy’s tasks, such as updating domain’s comments during import will not work if the write access to the default domain is restricted. quiesceDomain and unquiesceDomain tasks also require access to the default domain.

Note that by default DataPower uses a self-signed certificate for SSL. By default, DPBuddy ignores certificate validation errors. You can change this behavior by setting dp.trust.all.certs to false as described in Common Attributes/Options and Properties. If you choose this option, you will need to manually add the DataPower certificate to your JVM’s keystore.

It is highly recommended (although not absolutely required) to place all machines hosting DPBuddy and all DataPower appliances in the same time zone. DataPower relies on ZIP format for export/import; this means that file timestamps have no time zone information. This may lead to various issues if an export/import archive needs to be modified during your build/deployment process.

2.5. Configuring Apache Ant to Work with DPBuddy

Using DPBuddy from Apache Ant provides more flexibility and better integration with various build/deployment and release management tools than DPBuddy’s CLI. It is also more efficient since there is no need to start a JVM for every command.

DPBuddy requires Apache Ant 1.8 or above.

If you don’t have Apache Ant installed on your system, download and install it as documented at http://ant.apache.org/manual/install.html. Note that on many Linux systems you can also install Ant using a package manager, e.g., you can use apt-get -u install ant on Ubuntu. We also recommend running Ant with the -e option, as it provides a much cleaner output. You can set this option globally by setting the ANT_ARGS environment variable to -e.

DPBuddy tasks are packaged in a single Antlib. You may wish to familiarize yourself with the Ant documentation of the Antlib feature, especially the use of namespaces in Ant, before configuring DPBuddy tasks in your build file.

To declare DPBuddy tasks, add “taskdef” to your build file and point it to the DPBuddy installation:

<property name="dpbuddy.home" location="your location" />
<taskdef uri="antlib:com.myarch.dpbuddy">
     <classpath>
         <!-- Add conf directory to the classpath -->
         <pathelement location="${dpbuddy.home}/conf"/>
         <!-- We need to exclude Ant jars packages with DPBuddy -->
         <fileset dir="${dpbuddy.home}/lib" excludes="ant-*"/>
     </classpath>
 </classpath>

You must also declare the namespace used by DPBuddy tasks:

<project name="your project" xmlns:dp="antlib:com.myarch.dpbuddy" >

The namespace’s URI must match the URI used in taskdef. You must use antlib:com.myarch.dpbuddy as the URI.

You can also copy all the jar files that come with DPBuddy to ${user.home}/.ant/lib directory. If you choose this option, you don’t need to provide an explicit taskdef. Please consult the Ant manual for more details.

2.6. Verifying Connectivity with DataPower

To verify DPBuddy’s connectivity with DataPower, run the following command:

dpbuddy testConnection -url <your DataPower hostname> -user <your DataPower username> -password <your DataPower password> -domain default

Or from Ant:

<target name="test.connection" >
    <dp:testConnection url="your DataPower hostname" user="your DataPower username" password="your DataPower password" domain="default"/>
</target>

2.7. Advanced Configuration

If you’re planning to use DPBuddy to download or upload large binary files (bigger than 30MB), we recommend increasing the maximum heap size for the JVM used to run DPBuddy.

DPBuddy CLI supports the DPBUDDY_OPTS environment variable, which can be used to pass custom options to the JVM. By default, this variable is set to -Xms256m -Xmx1024m, meaning that the maximum heap size is set to 1GB.

To change the heap size for Ant, set the ANT_OPTS environment variable.

-Xmx1648m is the recommended setting for both Ant and DPBuddy CLI.

If you’re going to run DPBuddy behind a proxy, add the following Java system properties to the DPBUDDY_OPTS or ANT_OPTS variables: -Dhttps.proxyHost=<your proxy host> -Dhttps.proxyPort=<your proxy port> (note “https” prefix), or use Ant’s setProxy task.

2.8. DPBuddy License

All DPBuddy downloads are bundled with a 45-day evaluation license. You do not need to request or install the evaluation license; it is generated automatically when you run DPBuddy for the first time.

Once the evaluation license is expired, you’ll need to purchase the license from MyArch or request an extension of your trial license. Please send your request to license at myarch.com or submit it at http://myarch.com/dpbuddy-pricing.

To install a permanent license that you received from us, simply save the license file and add the property dpbuddy.license.file to your configuration file or Ant build file. This property must point to the location of the license file. Alternatively, you can provide the license option or attribute to a DPBuddy command or task. You can also set DPBUDDY_LICENSE_FILE environment variable to point to the license file.