.. highlight:: xml
.. index:: Auditing DPBuddy Tasks

.. _auditing:

Auditing DPBuddy Tasks/Commands
===============================

DPBuddy is capable of creating and maintaining an audit/log file tracking execution of the DPBuddy tasks that make changes to DataPower configuration or to the files residing on DataPower filesystems. The audited tasks include ``import``, ``delConfig``, ``copy``, ``delete`` and ``resetDomain``.

DPBuddy creates its audit file in XML format. The file contains a list of events. Each event represents an execution of one of the DPBuddy's tasks listed above.

An event contains the following data elements:

* Name of the task.

* Name of the local user who executed the task.

* Version/release info optionally supplied by the build process using ``dp.release.info`` property. This value can be used to specify the version of the DataPower artifacts that are being deployed to a domain.

* Timestamp of the event.

* DataPower URL.

* DataPower domain.

* DataPower user name used by the task.

* List of affected (updated or deleted) DataPower configuration objects.

* List of uploaded or deleted files. For uploaded files their source location/timestamp will be captured.

Here is an example of an event generated by the :ref:`import` task:

.. code-block:: xml

   <event>
       <action>import</action>
       <localUserName>developer1</localUserName>
       <releaseInfo>release-1.0.1</releaseInfo>
       <timestamp>2014-01-17 14:34:39</timestamp>
       <dpUrl>https://dp-test:5550/service/mgmt/current</dpUrl>
       <domain>test</domain>
       <dpUserName>dpbuddy</dpUserName>
       <objects>
           <object class="HTTPUserAgent" name="default" />
           <object class="XMLManager" name="default" />
           <object class="Matching" name="testFirewall" />
           <object class="StylePolicyAction"
               name="testFirewall_request_xform_0" />
           <object class="StylePolicyAction"
               name="testFirewall_request_results" />
           <object class="StylePolicyRule" name="testFirewall_request" />
           <object class="StylePolicy" name="testFirewall" />
           <object class="XMLFirewallService" name="testFirewall" />
       </objects>
       <files>
           <file localPath="D:\dobuddy\dpconfigs\XMLFirewall.xml"
               lastModified="2014-01-17 00:14:41" />
       </files>
   </event>

DPBuddy keeps the audit file in multiple places:

* The audit file is created and maintained on the machine where DPBuddy was executed. The location of the file is defined by ``dp.audit.local.file`` property.

* A copy of the audit file is also uploaded to the DataPower domain against which a DPBuddy task was executed. This copy of the file will contain only the events relevant to this domain and the device. If ``dp.audit.domain`` property was set to "default", the default domain will contain all audit entries for this device.

All audit files in all locations are updated independently. For every audit event DPBuddy will download the file from the target domain/device, update it with the new event and then upload the file back to the domain.

By default DPBuddy uploads the audit file to the root of the ``chkpoints:`` filesystem (as opposed to ``local:``). This is done so that the audit file does get exported when the entire ``local`` filesystem is exported and does not get deleted when ``local`` is cleaned. The location can be changed using ``dp.audit.dp.file`` property.

.. _properties_config:

Properties for Configuring Audit
--------------------------------

Similar to other :ref:`common DPBuddy properties <common_properties>`, every audit-related property has two aliases, one using dot as a word separator (following Ant's naming conventions) and the second one using lower camel case. The second alias should be used when running DPBuddy from Groovy or Gradle (or any other scripting language) since Ant naming conventions conflict with the commonly used dot notation for accessing object properties.

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

   * - Property name
     - Description
     - Required
   * - | dp.audit
       | dpAudit
     - If set to ``true``, create audit entries for auditable DPBuddy tasks.

       Defaults to ``false``.
     - No
   * - | dp.audit.local.file
       | dpAuditLocalFile
     - File name (including path) of the audit file on the machine where DPBuddy runs.

       Defaults to ``${tmpdir}/DPBuddy-audit-log.xml``. "tmpdir" is defined by the ``java.io.tmpdir`` system property of the JDK used to run DPBuddy.
     - No
   * - | dp.audit.save.to.dp
       | dpAuditSaveToDp
     - If set to ``true``, update the audit file on the device.

       Defaults to ``true``.
     - No
   * - | dp.audit.dp.file
       | dpAuditDpFile
     - File name (including path) of the audit file on the DataPower domain/device.

       Defaults to ``chkpoints:/dpbuddy-audit-log.xml``.
     - No
   * - | dp.audit.domain
       | dpAuditDomain
     - DataPower domain the audit file is saved (if ``dp.audit.save.to.dp`` is set to ``true``).

       Defaults to the target domain of an auditable task, i.e., if ``import`` runs against "TestDomain", this is where the audit file will be stored. Note that this results in each domain having its own audit file. Alternatively, if this property is set (e.g., to "default"), there will be a single audit file in the specified domain containing audit entries for all the domains of the device.
     - No
   * - | dp.release.info
       | dpReleaseInfo
     - Text to save in the ``releaseInfo`` field of the audit file. You can use this property to specify the version number of the released application and/or DataPower configuration.
     - No
   * - | dp.local.user
       | dpLocalUser
     - User ID of the user who executed the task that resulted in an audit event. If you run DPBuddy using a build server such as Jenkins, this property can be used to capture the logged-in name of the user who started the build.

       Defaults to: currently logged in user (``user.name`` system property in Java).
     - No