DPBuddy Installation and Configuration
======================================

.. _dpbuddyInstallation:

DPBuddy Installation
--------------------

DPBuddy requires Java SE Runtime Environment 6 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.

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 <http://myarch.com/download-dpbuddy>`_ 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``.

* 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 Software\JavaSoft\Prefs ...". 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 <http://stackoverflow.com/questions/16428098/groovy-shell-warning-could-not-open-create-prefs-root-node>`_.

.. _upgrading from dpbuddy 3.0:

Upgrading from DPBuddy 3.0 or DPBuddy 3.1
-----------------------------------------

The DPBuddy 3.2 distribution contains Apache Ant 1.9.4 jar files. To avoid classloader conflicts, exclude Ant jars from the taskdef used to define DPBuddy tasks:

.. code-block:: xml

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

All DPBuddy 3.2 tasks are backward compatible with 3.0.

.. _upgrading_from_dpbuddy_2_3:

Upgrading from DPBuddy 2.3
--------------------------

DPBuddy 3.1 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 :ref:`somaRequest`.

* The ``setConfig`` task was deprecated; use :ref:`import` instead.

* :ref:`modifyConfig` no longer supports the nested ``configFile`` element. You can replace it with the new :ref:`transform element <transform_elt>`.

* ``toDir`` is now a required attribute of the :ref:`copy`. You can also provide ``toDir`` at the nested ``dpFileset`` level.

* :ref:`Environment prefix mechanism <managing_env_vars>` has been substantially enhanced; you may need to change the way your properties are named to take advantage of the hierarchical prefixes.

.. _configuring_dp:

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 <http://pic.dhe.ibm.com/infocenter/wsdatap/v6r0m0/index.jsp?topic=%2Fcom.ibm.dp.xs.doc%2Flogging_internal.html&resultof%3D%2522%2569%256e%2574%2565%2572%256e%2561%256c%2522%2520%2522%2569%256e%2574%2565%2572%256e%2522%2520%2522%256c%256f%2567%2567%2569%256e%2567%2522%2520%2522%256c%256f%2567%2522%2520>`_. 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. :ref:`quiesceDomain` 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 :ref:`Common Attributes/Options and Properties <connection_options>`. 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.

.. _configuring_ant:

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 <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 <http://ant.apache.org/manual/running.html>`_ 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 <https://ant.apache.org/manual/Types/antlib.html>`_, 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:

.. code-block:: xml

   <property name="dpbuddy.home" location="your location" />
   <taskdef uri="antlib:com.myarch.dpbuddy">
        <classpath>
            <!-- 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:

.. code-block:: xml

   <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 <http://ant.apache.org/manual/running.html>`_ for more details.

.. _verifying_connectivity:

Verifying Connectivity with DataPower
-------------------------------------

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

.. code-block:: bat

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

Or from Ant:

.. code-block:: xml

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

.. _advanced_configuration:

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 <http://ant.apache.org/manual/running.html#options/>`_ 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 <https://ant.apache.org/manual/proxy.html>`_.

.. _dpbuddy_license:

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 <mailto:license@myarch.com>`_ or submit it at `http://myarch.com/dpbuddy-pricing <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.