Installation Configurations

DirX Audit supports several installation environments. This section describes two typical installation configurations:

A complete local installation on a single machine
A sample distributed installation on several machines

Installation Prerequisites

The Java Virtual Machine (Java VM, JVM) is required for the DirX Audit installation. The installation will not start without Java VM installed; instead, it displays an error message indicating that a valid Java VM is missing.

When the installation runs, it prompts you to identify the folder in which the Java VM is installed. Make sure you have an appropriate Java VM installed.

You must also check whether the JAVA_HOME and PATH environment variables are set correctly for your operating system.

If you need to upgrade your Java VM installation later on, follow these steps:

Stop the Apache Tomcat (for DirX Audit Manager), DirX Audit Message Broker and DirX Audit Server services for all configured tenants.
Upgrade your Java VM installation with a newer version.
If you have extended JVM installation with additional files, for example with the mssql-jdbc_auth-<version>-<arch>.dll file to support integrated Windows authentication in database connectivity or your proprietary copy of the cacerts file, you must deploy also these files in this step.
Check that the JVM path reference is still valid in the following files: install_path/dxtrunenv.bat and install_path/conf/installation.ini.
Start the Apache Tomcat (for DirX Audit Manager), DirX Audit Message Broker and DirX Audit Server services for all configured tenants manually.
Check that the services run correctly.

See the DirX Audit Release Notes for supported versions.

Local Installation

To install all DirX Audit components on a single machine:

Install and prepare the Apache Tomcat if you plan to run DirX Audit Manager and stop the service before DirX Audit installation.
Run the DirX Audit installation procedure.
In the Choose Install Set dialog, select All. Message Broker, Server application, Manager application and Tools will be selected.
(Optional) Install Oracle Database JDBC driver.
Perform the DirX Audit configuration procedure. Now your system is ready to run.

Distributed Installation

You can also distribute the DirX Audit components across different machines.

If you install DirX Audit in a distributed environment, be sure to update all machines with the new DirX Audit software version. Otherwise, severe inter-operational problems could result.

An example for a high level of distribution is:

DirX Audit Message Broker runs on machine A.
DirX Audit Server application containers for all configured tenants and Tools reside on machine B.
DirX Audit Manager application container resides on machine C.

To set up this environment:

Install the DirX Audit Message Broker on machine A:
1. Run the installation and configuration procedure.
2. In the Choose Install Set dialog, select Message Broker.
3. Configure DirX Audit Message Broker.
Install the DirX Audit Server application and its containers on machine B:
1. Run the installation and configuration procedure.
2. In the Choose Install Set dialog, select Server in Install Set. Server application and Tools are selected in the component tree.
3. (Optional) Install Oracle Database JDBC driver.
4. Configure DirX Audit Server for each tenant.
Install the DirX Audit Manager application and its container on machine C:
1. Install and prepare the Apache Tomcat and stop the service before DirX Audit Manager installation.
2. Run the installation procedure.
3. In the Choose Install Set dialog, select Manager in Install Set. Manager application is selected in the component tree.
4. (Optional) Install Oracle Database JDBC driver.
5. Configure DirX Audit Manager.

Apache Tomcat Installation

To run DirX Audit Manager, you must install Apache Tomcat, which serves as the DirX Audit Manager’s container, from the web site http://tomcat.apache.org. See the DirX Audit Release Notes for supported subversions.

The documentation assumes that Apache Tomcat is installed in the tomcat_install_path folder.

Make sure that the Apache Tomcat service is running under an account which has same access rights to the DirX Audit deployment as the one used for the DirX Audit installation and configuration so that the Apache Tomcat container used for the DirX Manager can access all DirX Audit resources. Typically, the service account can be the same as the one used for the product installation.

We recommend extending the Tomcat Java Options, especially when running both the DirX Audit Manager and the DirX Identity Web Center using the same Tomcat installation (the following description applies to the Microsoft Windows platform):

Start tomcat_install_path\bin\Tomcatversionw.exe.
Select the Java tab.
Set at least 2048 to Maximum memory pool.
Click Apply and then click OK.

If you are upgrading from older versions of DirX Audit, be aware that service support for running Apache Tomcat has been removed from DirX Audit Configuration Wizard. To create, configure and run Tomcat (and DirX Audit Manager), use only the service provided by Tomcat installation (as described here). For other platforms, see the Apache Tomcat documentation. If you had the service provided by DirX Audit in the old installation (service DirX Audit Manager X.Y), this service was removed during the upgrade procedure.

We strongly recommend that you run the DirX Audit Manager application via the HTTPS protocol. See the Tomcat documentation for details; for example, https://tomcat.apache.org/tomcat-9.0-doc/ssl-howto.html.

Support for Windows Authentication in Database Connectivity

If you want to use integrated Windows authentication in database connectivity, you must copy the mssql-jdbc_auth-<version>-<arch>.dll file into the jvm_install_path\bin folder where jvm_install_path represents Java Virtual Machine installation location. The dynamic-link library is distributed together with the Microsoft JDBC Driver for SQL Server.

For details on the Windows authentication in database connectivity, see the chapter “Using the Configuration Wizard for the Tenant Configuration”.

Oracle Database JDBC Driver Installation

To run Oracle Database as the DirX Audit Database, you must install Oracle Database JDBC driver for the supported Java installation and your version of Oracle Database. See the DirX Audit Release Notes for the supported Java version.

The JDBC driver (.jar file only) must be copied to the following location:

install_path/lib/, where install_path represents the DirX Audit installation location.

Silent Installation

DirX Audit can be also installed without any interaction (silent mode). Follow these steps to create a silent setup:

Copy the contents of the folder install_media/DirXAudit/selected_platform from the DVD to a folder on your machine.
Customize the installation properties file dirxaudt.properties as described in this section.
Start the installation program in the folder on your machine. Check for errors

The dirxaudt.properties file contents are as follows:

…
# UI mode for the installer.
# Options: SILENT, CONSOLE or GUI
# Default for Windows:
# INSTALLER_UI=GUI
# Default for Unix:
# INSTALLER_UI=CONSOLE
#
# INSTALLER_UI=<mode>
# Installation property file (this file) given for installation.
# It's used internally for checking if silent installation has this file.
# Set to 1 to use this file. The file will be ignored if set to 0.
PROP_USE_FILE=0
###############################################################
#
# DirX Audit specific properties
#
###############################################################
# -------------------------------------------------------------
# Only for Unix in silent installation and running as root!
# If the installation runs under root, you have to set the user name.
# DirX Audit will be installed under the account of an existing user.
# The user and group must already exist!
# Target Unix user (username or UID)
# PROP_UNIX_USER=<user>
# Target Unix user group (groupname or GID)
# PROP_UNIX_USER_GROUP=<group>
# --------------------------------------------------------------
# Installation path
# Default for Windows:
# PROP_USER_INSTALL_DIR=$PROGRAMS_DIR$$/$Atos$/$DirX Audit
# Default for Unix (installing as root):
# PROP_USER_INSTALL_DIR=$UNIX_OPT$$/$DirX_Audit
# Default for Unix (installing as normal user):
# PROP_USER_INSTALL_DIR=$PROGRAMS_DIR$$/$DirX_Audit
#
# PROP_USER_INSTALL_DIR=<path>
# -------------------------------------------------------------
# Program group for DirX Audit.
# Default:
# PROP_USER_SHORTCUTS=$WIN_COMMON_PROGRAMS_MENU$$/$Atos DirX Audit V<version>
#
# PROP_USER_SHORTCUTS=<program group>
# -------------------------------------------------------------
# Java VM for DirX Audit.
#
# PROP_JAVA_HOME=C:\\Program Files\\Java\\jre11
# -------------------------------------------------------------
# Selected licenses for DirX Audit
# <license>=[1 | 0]
# 1: license will be selected.
# 0: license will be not selected.
# Support for DirX Identity:
PROP_LIC_PROD_DXI=1
# Support for DirX Access:
PROP_LIC_PROD_DXA=1
# Support for Dashboard components.
PROP_LIC_COMP_Dashboard=1
# Support for History DB components.
PROP_LIC_COMP_HistoryDB=1
# -------------------------------------------------------------
# Install features for DirX Audit
# <feature>=[1 | 0]
# 1: feature will be installed
# 0: feature will be not installed
# Message broker.
PROP_FEAT_Message_Broker=1
# Server container and server application deployment.
PROP_FEAT_Server=1
# Manager application deployment.
PROP_FEAT_Manager=1
# Tools.
PROP_FEAT_Tools=1
# -------------------------------------------------------------
# Force Windows restart - (De)-Installation in silent mode
# Note:
# Set to YES when you want to force a reboot after (de-)installation.
#
# PROP_RESTART_NEEDED=YES
# -------------------------------------------------------------
# Specific InstallAnywhere options for installation.
# File overwrite
# -fileOverwrite_c\:\\example_file.txt=Yes

To configure this file for silent installation and other customizations:

Uncomment the # INSTALLER_UI=<mode> line and change it to INSTALLER_UI=SILENT. This step is not necessary if the installer is started with the argument -i silent (which enforces silent mode).
Set the value PROP_USE_FILE to 1 if you want to use the customized values from this file. The settings in the file will be ignored if this property value is not set to 1.
Customize the PROP_LIC_… values according to the features you have licensed, specifying the 1 value for features you have licensed and the 0 value for features you have not licensed.
Change (and uncomment) the PROP_… values in the section starting with # DirX Audit specific properties if you do not wish to use the respective default settings.
To select a Java VM for DirX Audit that is already installed, customize and uncomment the setting for the property PROP_JAVA_HOME according to the inline comments shown in the file contents shown in this section.

The installation properties file must be located in the same folder as the installer and the base name (the file name that precedes the extension) must be the same as the base name of the installer binary.

Configuring a silent installation implicitly configures a subsequent silent un-installation because the UI mode you specify in the installation properties file applies to both the installer and uninstaller binaries. As a result, an uninstallation performed after a silent installation will automatically run in silent mode unless you specify a different mode with command line arguments.

Preparing Truststores and Keystores for SSL Configuration

We recommend communicating over secure channels between components and services. To set up this environment, you must supply cryptographic material stored in Java keystores and truststores for each endpoint that will communicate over a secure channel. The Configuration Wizard will ask you for these files.

The next sections explain how to prepare individual truststores and keystores (using a newly created Certificate Authority). If you have a general certification service in your company, you should use it to create the certificates instead of creating your own as described in this section. If these certificates are globally trusted by the Java JVM selected for DirX Audit (or you add your company CA certificates to this JVM default Certificate Authority (ca) store) you can omit creating the truststores (as no additional stores are required if your JVM already trusts your certificates).

The recommended location for all keystores and truststores is the folder install_path/conf/crypto/stores.

For more information, see the section “Managing the Cryptographic Material” in the DirX Audit Administration Guide.

Preparing the LDAP Truststore for Authentication and LDAP Collector Configuration

DirX Audit allows you to configure LDAP over SSL (LDAPS) for establishing secure SSL/TLS connections to the LDAP directory server.You must prepare a truststore for this configuration and use it in the “Common Authentication Configuration” step during the tenant configuration.If you are using the same LDAP server for both the authentication and LDAP collector you can create only one truststore and use it in both configurations screens (authentication and LDAP server collector).

To prepare an LDAP truststore:

Export the DirX Directory server and Certificate Authority (CA) certificates to files.
Import the DirX Directory server and CA certificates to the truststore.

The next sections detail these tasks.The final truststore file will be named ldap-ts.jks.

Exporting the DirX Directory Certificates

To export the DirX Directory certificates to files:

Run DirX Directory Manager. In the Configuration section, select ldapSSLConfiguration under LDAP Configuration Subentries.
Select the DirX Directory certificate and then click the disk icon Export to PEM to export the server certificate into a PEM file; for example, dirx_directory.pem.
Edit the generated file and remove all sections containing private keys – all lines between (including) -----BEGIN ENCRYPTED PRIVATE KEY----- and -----END ENCRYPTED PRIVATE KEY-----.

If there are more certificate entries remaining in the file (there are lines between the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines), you need to split them into separate files and import them one by one. Typically, the exported file will contain two such entries – the first is the server certificate and the second is the CA (Certificate Authority that signed the server certificate) certificate. You need to import all of these into the truststore. For the purpose of the next example, let’s assume that you have two of these separate certificates exported: one for the server certificate named server.pem and the CA certificate named ca.pem.

Importing the DirX Directory Server and CA Certificates

Run the command prompt and navigate to the location where you have separate certificates exported.
Import the server certificate server.pem into the truststore ldap-ts.jks. Run the following command, enter the password and then press Enter:

    keytool -keystore ldap-ts.jks -importcert -alias dirxserver -file server.pem

Import the CA certificate ca.pem into the truststore ldap-ts.jks:

    keytool -keystore ldap-ts.jks -importcert -alias dirxca -file ca.pem

Preparing the DirX Access Server Secure Connection

To set up the secure connection to DirX Access Server when a DirX Access PEP is configured in the DirX Audit authorization settings, you need to use the relevant DirX Access Server certificate and the relevant DirX Access Server CA certificate (the Certificate Authority that signed the server certificate) from the DirX Access Server. You need to create your own truststore containing the exported certificates and then use this truststore in the DirX Audit Authorization - DirX Access PEP configuration.

Preparing the LDAP Collector

If you set up the collector for the same LDAP server as you are using for authentication, you can use the truststore you already created or create a new one by following the steps described in the section "Preparing the LDAP Truststore".

You must use the prepared truststore described in the Tenant configuration procedure’s “Server LDAP Collector for DirX Identity Format” step for establishing secure SSL/TLS connection to the server LDAP collector.

Preparing the Message Broker

DirX Audit allows you to configure Message Broker over SSL to establish secure SSL/TLS connections to the Broker and the Broker admin console. You must prepare a keystore and a truststore for this configuration and use them in the Message Broker Connectivity step in the Core configuration.

If you want to use SSL for connecting DirX Identity JMS Audit Handler to the DirX Audit Message Broker, make sure to import the CA certificate of the broker into the truststore of the Java VM running the IdS-J server. For more information, see the DirX Identity Installation Guide.

The keystore contains the private key for the Broker and the admin console and is used by the Broker.

The truststore contains the public certificate of the Broker and the Certificate Authority (CA) and is used by the Broker and all clients (for example, the Server JMS collectors, Identity Audit Plugin and DirX Access Audit Plugin).

To prepare the Message Broker certificates:

Create the CA certificate in the file dxt-ca.jks.
Create the Message Broker keystore in the file broker-ks.jks.
Create the Message Broker truststore in the file broker-ts.jks.

The next sections detail these tasks.

Creating the CA Certificate

To create the CA certificate:

Create the keystore file dxt-ca.jks and then create a new CA key and certificate with the validity of 10 years (3650 days)

    keytool -genkeypair -keystore dxt-ca.jks -alias dxtca -keyalg RSA -dname CN=DXTCA,O=Demo -ext bc:c -validity 3650

Export the CA certificate in the PEM format:

    keytool -keystore dxt-ca.jks -alias dxtca -exportcert -rfc > dxt-ca.pem

Creating the Message Broker Keystore

To create the keystore:

Create the keystore file broker-ks.jks and create a new key for the Broker. The given CN should match the hostname of the machine:

    keytool -genkeypair -keystore broker-ks.jks -alias broker -keyalg RSA -dname CN=server.demo.org,O=Demo

Create the certificate signing request for this certificate:

    keytool -keystore broker-ks.jks -certreq -alias broker > broker.csr

Sign the prepared certificate with your CA (for the validity of 5 years) and export it into PEM format. The specified DNS extension must match the full hostname of the machine where the broker is installed:

    keytool -keystore dxt-ca.jks -gencert -alias dxtca -ext ku:c=dig,keyEncipherment,keyAgreement -ext san=dns:server.demo.org -validity 1825 -rfc -infile broker.csr > broker.pem

Combine the CA and server certificate and import the signed certificate back to the keystore:
Windows: copy dxt-ca.pem+broker.pem chain.pem
Linux: cat dxt-ca.pem broker.pem >chain.pem

    keytool -keystore broker-ks.jks -importcert -alias broker -file chain.pem

Creating the Message Broker Truststore

To create the truststore:

Import the CA certificate to the truststore broker-ts.jks:

    keytool -keystore broker-ts.jks -importcert -alias dxtca -file dxt-ca.pem

Import the server certificate to the truststore:

    keytool -keystore broker-ts.jks -importcert -alias broker -file broker.pem