Audit Module Deployment

Last modified by jhurst on 2022/04/28 16:42

 Audit Module Deployment For DigDash Enterprise

This document explains how to deploy the audit module integrated into DigDash Enterprise. This module allows an administrator of the system to retrieve the list of data cubes and flows and the history of all user sessions.

Module Installation

The audit module is delivered as a zip file compatible with the DigDash Enteprise backup restore. Here is the process to deploy this module:

  1. Connect to DigDash Enterprise home page with a web browser (default is http://localhost:8080/adminconsole)
  2. Click on Configuration, then Backup Management and Restore
  3. If not already done, login with the DigDash Enteprise super administrator user
  4. Click on button Browse File...
  5. In the file selector, browse to the folder <DD install>/add-ons/ddaudit and choose the file ddaudit_module.zip
  6. Click on Load button
  7. Confirm the import options by clicking on Validate button
  8. Restart your server

At the end of the import operation, DigDash Enterprise has a new DDAudit role containing:

  • Pre-defined data models to create visualizations on audit data
  • Pre-defined flows: cubes lists, flows list and user sessions lists
  • Pre-defined dashboard pages to display audit data

Access to the DigDash Enterprise audit data

To visualize this information, you must add the DDAudit role to your DigDash Enterprise administrator, or any other user you choose for this task.

From the Server Status page, start the audit services you want to use (Sessions, Cubes and Flows audit services).

The pre-defined reports are directly available in the Server Status page, or in the Information Wallet of users with DDAudit role.

You can also create your own flows based on the pre-defined data models, and new data models on the audit database.

Managing DDAudit Database files

Migration from a previous version of the audit module

If you had deployed a the audit module in a previous DigDash Enterprise build (before the 2014B0603), the name of the audit H2 database was then DDAudit.

From version 2014B0603 this name has changed by default into DDAudit_<DDE domain> to accommodate multi-domains deployment on the same server. After this change the previous audit data are not available anymore in the new version of DigDash Enterprise.

To retrieve them, there are 2 possible migration scenarios :

  • Option 1 (recommended): By renaming the old DDAudit database into DDAudit_<DDE domain> (by default the DDE domain name is ddenterpriseapi),
  • Option 2 : By referencing the old DDAudit database name into the new DigDash Enterprise version (web.xml modification).

Option 1 (recommended) : Renaming the old DDAudit database

Choose this option if you did not modify the DDAudit data models, or if you do not want to keep these modifications. The modification of audit flows and/or audit dashboards is not significant for this option.

Migration procedure for option 1

  1. Stop DigDash Enterprise servers
  2. Find the files DDAudit.h2.db et DDAudit.trace.db on the server computer:
  • On Windows these files can be found in the installation folder of DigDash Enterprise if the server is manually started using start_servers.bat, or <Windows>/System32 if the server is started as a Windows service.
  • On Linux, depending on the system configuration, these files can be found in your Tomcat installation folder (usually at the same place than the logs).
  1. Process these files as below:
  • Copy and rename DDAudit.h2.db into DDAudit_<DDE domain>.h2.db (example: DDAudit_ddenterpriseapi.h2.db)
  • Copy and rename DDAudit.trace.db into DDAudit__<DDE domain>.trace.db (example: DDAudit_ddenterpriseapi.trace.db)
  1. Start DigDash Enterprise servers
  2. Deploy the new audit module (chapter I) so the audit data models correctly access the new audit database.

Option 2: Modification of web.xml to link to the old DDAudit database

Choose this option if you modified the DDAudit data models. The modification of audit flows and/or audit dashboards is not significant for this option. Warning: If you have several ddenterpriseapi_xxxx on the same Tomcat, it is recommended to migrate only for one domain because the DDAudit database can not be used by different domains at the same time.

Migration procedure for option 2:

  1. If this is a first start after a DigDash Enteprise upgrade (new war files), start the Tomcat server and wait for the full deployment of the new war files. As soon as Tomcat has fully started (the message Server startup in xxxx ms shows in Tomcat console), stop DigDash Enterprise servers.
  2. Edit the file <DigDash Enterprise install>/apache-tomcat/webapps/ddenterpriseapi/WEB-INF/web.xml.
  • Change the value of parameter audit.db.url from jdbc:h2:DDAudit_${server.DomainName};AUTO_SERVER=TRUE into jdbc:h2:DDAudit
  1. Start DigDash Enterprise servers

Changing the location of the DDAudit database files

By default, the DDAudit database files are stored in the Tomcat work directory. In some configurations this path may not be the default <DDE Install> folder.

For example, on Linux the location may be the Tomcat installation folder, and default user rights may prevent the server to write files in that folder. DDAudit would not work in this case.

Another example is for Windows, when Tomcat is started as a service, the DDAudit files could land in Windows/system32 folder.

You can change the location of the DDAudit database files with the following procedure:

  1. Stop DigDash Enterprise server
  2. Edit the file <DigDash Enterprise install>/apache-tomcat/webapps/ddenterpriseapi/WEB-INF/web.xml.

    • Change the value of parameter audit.db.url from jdbc:h2:DDAudit_${server.DomainName};AUTO_SERVER=TRUE into jdbc:h2:file:/home/audit/DDAudit_${server.DomainName};AUTO_SERVER=TRUE (notice the “file:” inserted at the start of the URL)
  1. Make sure this folder exists and move all the existing DDAudit*.db files to the new location
  2. Start DigDash Enterprise server

Note: The parameters audit.db.url, audit.db.user, audit.db.password and audit.db.tcpServer can be specified as JVM lauch parameters, for instance by adding them to the JAVA_OPTS variable (setenv.bat, setenv.sh…) or in catalina.properties: JAVA_OPTS=[…] -Daudit.db.url=jdbc:h2:file:/home/DDAudit;AUTO_SERVER=TRUE [...]

Another alternative is to change the value of parameter h2.baseDir, which changes the behavior for all H2 bases (DDAudit but also DDComments):

  1. Stop DigDash Enterprise server
  2. Locate and edit the catalina.properties file on the server hard drive (ex: <DDE Install>/apache-tomcat/conf/catalina.properties on DigDash Enterprise Windows installation)
  3. Add the following line:

    h2.baseDir=/the/new/db/path

    Note: This path can be relative to the initial Tomcat workdir (ex: h2.baseDir=./db)

  4. Make sure this folder exists and move all the existing DDAudit*.db files to the new location
  5. Start DigDash Enterprise server