Quick Start Guide

The easiest way to get started with DPBuddy is to use its docker image:

docker pull myarch/dpbuddy:3.4
docker volume create dpbuddy-work
docker create -it --name dpbuddy -v dpbuddy-work:/opt/dpbuddy/src myarch/dpbuddy:3.4

You can later further customize your docker configuration.

You can now start the container:

docker start -i dpbuddy

Without docker, you can install DPBuddy from its distribution:

  • Install Java if it’s not already installed. DPBuddy supports any flavor of Java 7 and Java 8/9, including Oracle, IBM and OpenJDK. If you already have Java 7 installed, make sure that the latest updates are applied. Make sure that you can run “java” from command line, e.g., java -version.
  • Download DPBuddy and unzip/untar the content of the file into a directory, e.g., c:\dpbuddy or /opt/dpbuddy:
  • Define the DPBUDDY_HOME environment variable and point it to the directory containing the DPBuddy installation, e.g., c:\dpbuddy\dpbuddy-3.4 or /opt/dpbuddy/dpbuddy-3.4.
  • Add %DPBUDDY_HOME%\bin or $DPBUDDY_HOME/bin to your PATH environment variable. On Linux, make sure that $DPBUDDY_HOME/bin/dpbuddy has the “execute” permission, run the appropriate “chmod” command if it does not.

On Linux, you can add these lines to your .bashrc:

export DPBUDDY_HOME=/opt/dpbuddy/dpbuddy-3.4
export PATH=$DPBUDDY_HOME/bin:$PATH

On Windows, you can simply run these commands from the command line or update environment variables (Control Panel/System Properties/Environment Variables…):

set DPBUDDY_HOME=c:\dpbuddy\dpbuddy-3.4
set PATH=%DPBUDDY_HOME%\bin;%PATH%

Once DPBuddy is installed, type dpbuddy -h in a command line/terminal window. You should see a help screen containing the list of commands and options supported by the tool.

Now configure your DataPower appliances:

  • Login to each appliance and enable XML Management if it’s not already enabled. (Network/Management/XML Management).
  • 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.
  • Create a user account that will be used by DPBuddy. Make sure that you’re able to login to WebGUI using this account and that the password was reset. The account does not have to be a privileged account, unless you want to be able to perform domain-level operations (restart domain, quiesce domain) using DPBuddy.

Define your DataPower connection parameters in dpbuddy.conf file. dpbuddy.conf could reside anywhere, but to get started you can use the dpbuddy.starter.conf file in $DPBUDDY_HOME/conf (e.g., c:\dpbuddy\dpbuddy-3.4\conf or /opt/dpbuddy/dpbuddy-3.4/conf):

  • If you’re using the docker image, copy dpbuddy.starter.conf to the src directory: cp /opt/dpbuddy/conf/dpbuddy.starter.conf /opt/dpbuddy/src/dpbuddy.conf.
  • Without docker, rename dpbuddy.starter.conf to dpbuddy.conf. Keep dpbuddy.conf in the “conf” folder.
  • Update your DataPower host(s) and the username/password for the DPBuddy account created earlier.

Your dpbuddy.conf file could look like this:

// Username that DPBuddy will use to login to DataPower
dpUsername: dpbuddy
dpPassword: 12345

dev: {
    dpUrl: dp1-host
    dpDomain: dev
}

test: {
    dpUrl: dp2-host
    dpDomain: test
}

You’re now ready to run DPBuddy. First, run the connect command to make sure that you’re able to connect to DataPower. Provide the name of the environment defined in dpbuddy.conf:

dpbuddy connect -env dev

connect prints some basic information about your appliance, including its firmware version. If you get any connection or authentication errors, please verify your domain name and username and password that you specified in “dpbuddy.conf”. Note that DataPower raises an authentication exception if the domain that you provided does not exist.

If connect does not print any appliance information, verify that you’re able to login to the appliance using the username/password from “dpbuddy.conf”. If you just created the account, make sure that the password was reset.

You can use -h with any command to see the list of available options, e.g. dpbuddy import -h.

You can now export one of the domains:

dpbuddy export -file dev-domain.zip -env dev

This command will export all objects in the domain. If you’d like to export only a subset of objects, first run listObjects to see all objects in the domain:

dpbuddy listObjects -env dev

You can then filter objects using the -objects option:

dpbuddy listObjects -objects WSGateway -env dev

To export only the gateways (and their dependent objects), run the following command:

dpbuddy export -file dev-domain.zip -objects WSGateway -env dev

You can now import the exported objects into another domain. The target domain has to exist.

dpbuddy import -file dev-domain.zip -save -env test

This command will import the exported objects into the “test” environment and it will also save the domain’s configuration.

To verify that all gateways in the domain are up and running, run the assertState command:

dpbuddy assertState -activeService -objects WSGateway -env dev