Required Configuration Parameters

JDBC Driver Directory and JDBC Drivers

XDM uses JDBC to access all source and target databases. You must provide vendor JDBC 4+ drivers and tell XDM where to find them.

JDBC driver configuration

XDM uses the JDBC API to access the source and target databases of your tasks. You must provide suitable JDBC version 4.0 (or higher) drivers for all database systems that you plan to use as the source or target for XDM tasks.

XDM will search for JDBC drivers in the directory xdm-config/jdbc-drivers. Copy all required JDBC driver .jar files into this directory.

You can download JDBC drivers for different relational database systems on the websites of the respective database vendors. The following table shows the file names that are typically used by the database vendors. Note that vendors can choose different file names for future releases of their JDBC drivers.

XDM has a Postgres JDBC driver included in the distribution. This driver is used by default. It’s not necessary to add an extra Postgres JDBC driver to the driver directory.

Table 1. Typical JDBC driver file names(s) for different database systems
Database system	Driver file name(s)
Db2 for Linux, UNIX, and Windows	db2jcc4.jar
Db2 for z/OS	db2jcc4.jar and db2jcc_license_cisuz.jar
Oracle	ojdbc7.jar
PostgreSQL	postgresql-<version>.jar
Microsoft SQL Server	mssql-jdbc-<version>.jre11.jar
MySQL	mysql-connector-java-<version>.jar
MariaDB	mariadb-java-client-<version>.jar
Google Big Query	GoogleBigQueryJDBC42.jar plus additional dependencies

When a new driver was added to the driver directory, the docker-composer of XDM must be restarted to register the new driver in XDM.

Driver directory

The directory where XDM searches for JDBC drivers can be configured with the property xdm.core.jdbc-driver-dir. The default directory is /xdm/config/jdbc-drivers/ which is used when no other value is specified. When changing the default, it must be specified in the environment sections of both, core and dataflow server. The following configuration shows the default setting.

xdm.core.jdbc-driver-dir=/xdm/config/jdbc-drivers/

Additional drivers to load

The property xdm.core.registered-jdbc-driver specifies a comma separated list of additional JDBC driver names to load. This property can only be used in the environment section of the dataflow server and the default is an empty list. IBM’s AS400 and IMS drivers are always implicitly added to this list. Specifying driver names is only necessary if the driver can not be automatically loaded, as it is the case for the two IBM drivers. The following line shows how a driver with the fully qualified name org.vendor.jdbc.someDriverName would be added to the list.

xdm.core.registered-jdbc-driver=org.vendor.jdbc.someDriverName

Kubernetes
Docker

You can execute wget commands to download the required JDBC drivers. The Helm Chart will make sure that the JDBC drivers are mounted to their respective pods. The driver files must be stored in the directory /xdm/config/jdbc-drivers. You can use the wget option -P to specify the target directory, in which the files will be stored.

Parameters:

Directory: fixed to /xdm/config/jdbc-drivers/ (can be overridden)

Download: xdm.jdbcDriversCommand

xdm:
  jdbcDriversCommand: |-
    wget -P /xdm/config/jdbc-drivers/ -v --no-check-certificate https://example.com/db2jcc4.jar
    wget -P /xdm/config/jdbc-drivers/ -v --no-check-certificate https://example.com/ojdbc8.jar

Parameters:

Directory: xdm.core.jdbc-driver-dir
JARs: files in xdm-config/jdbc-drivers/

Optional: xdm.core.registered-jdbc-driver

services:
  core-server:
    volumes:
      - ./xdm-config:/xdm/config:ro
    environment:
      - xdm.core.jdbc-driver-dir=/xdm/config/jdbc-drivers/
  dataflow-server:
    volumes:
      - ./xdm-config:/xdm/config:ro
    environment:
      - xdm.core.jdbc-driver-dir=/xdm/config/jdbc-drivers/
# Place driver JARs in ./xdm-config/jdbc-drivers/

JDBC Driver configuration for Google Big Query

For being able to use the JDBC driver for Google Big Query that was mentioned above, it is necessary to add some additional dependencies. You can either add them directly into the driver directory or build a super JAR that consists of the actual JDBC driver for Google Big Query and all other necessary dependencies. The latter is recommended. The dependencies that have to be included are listed below.

google-api-client from group com.google.api-client (version 2.2.0)
google-auth-library-oauth2-http from group com.google.auth (version 1.16.0 or higher)
google-http-client-jackson2 from group com.google.http-client (version 1.43.1 or higher)
google-api-services-bigquery from group com.google.apis (version v2-rev20230210-2.0.0)
google-api-services-iamcredentials from group com.google.apis (version v1-rev20211203-2.0.0)
gax from group com.google.api (version 2.23.3 or higher)
google-cloud-bigquerystorage from group com.google.cloud (version 2.34.0)
guava from group com.google.guava (version 31.1-jre or higher)
avro from group org.apache.avro (version 1.11.1)
joda-time from group joda-time (version 2.12.5)

License key

XDM requires a valid license key. Without a license key XDM will not start. The license key is provided by UBS Hainer GmbH.

Kubernetes
Docker

The license key can be set as an inline license in the values.yml or as a secret in a file xdm-license. As an alternative to storing the license as plaintext, a Kubernetes secret can be used. The name of the secret can be chosen freely, whereas the key name in which the license data is stored has to be 'license.txt'. The content of the secret should be base64 encoded to keep the line breaks in the license key.

Parameters:

Inline license: xdm.license

Or secret: xdm.licenseSecret

xdm:
  # Option 1: inline license
  license: |
    LICENSE = 26,XXXXXXXX...
    LIC0001 = COMPANY:YourCompany
    LIC0002 = PRODUCT:XDM3
    ...

  # Option 2: license from secret
  licenseSecret: xdm-license

The license key must be stored in a file called license.txt inside the XDM core configuration directory. The path to this directory is specified in the docker-compose.yml file. By default, XDM uses the directory xdm-config.

Parameters:

license file: xdm-config/license.txt

services:
  core-server:
    volumes:
      - ./xdm-config:/xdm/config:ro
  dataflow-server:
    volumes:
      - ./xdm-config:/xdm/config:ro

# ./xdm-config/license.txt contains the license text

UI server URI

Configuring UI Server URI

Overview

The UI server URI defines the external URL under which users access the XDM web interface. In containerized deployments with Docker Compose or Kubernetes, you must align the base URL, the UI context path, and OAuth2 redirect URIs so that:

users can open the UI in their browsers,
redirects work correctly, and
OAuth2 logins (for example with Keycloak) succeed.

This logical aspects must be configured:

Base URL (UI server URI) that users see in their browsers
UI context path (if the UI is not at the root path /)
OAuth2 redirect URIs that point back to the XDM UI

Parameters:

contextPath

Defines the context path under which the UI is exposed. In the example above, the UI is available at https://xdm.example.com/xdm.

userManagement.oauth2.registration.*.redirect-uri (Kubernetes only)

Defines the OAuth2 redirect URI(s) that the identity provider (for example Keycloak) will call after login. The URI must:

use the externally visible host name and protocol,
include the configured context path, and
end with the OAuth2 login path (for example /api/login/oauth2/code/keycloak).

xdm.core.ui.serverUri* (Docker only)

Specifies the full UI server URI as seen by users, including protocol, host, and context path. In the example above:

xdm.core.ui.serverUri=https://xdm.example.com/xdm

Kubernetes
Docker

Parameters:

xdm.environment.contextPath

OAuth2 redirect URIs in userManagement.oauth2.registration.*.redirect-uri

xdm:
  environment:
    contextPath: /xdm

userManagement:
  oauth2:
    registration:
      keycloak:
        redirect-uri: https://xdm.example.com/xdm/api/login/oauth2/code/keycloak

Parameters:

xdm.core.ui.serverUri
UI context path: xdm_context_path

services:
  core-server:
    environment:
      - xdm.core.ui.serverUri=https://xdm.example.com/xdm
  web-ui:
    environment:
      - xdm_context_path=xdm/

Time zone

Controls the time zone used by all XDM containers (logs, schedules, timestamps). The default is Europe/Berlin. If the XDM installation should use a different time zone specify one of the following values:

Table 2. Time zone names (not exhaustive)
Name	Description
UTC	Coordinated Universal Time
US/Pacific	United States Pacific Time (UTC-08:00)
US/Mountain	United States Mountain Time (UTC-07:00)
US/Central	United States Central Time (UTC-06:00)
US/Eastern	United States Eastern Time (UTC-05:00)
Europe/London	Western European Time (UTC+00:00)
Europe/Berlin	Central European Time (UTC+01:00)
Europe/Vilnius	Eastern European Time (UTC+02:00)
Asia/Tel_Aviv	Israel Standard Time (UTC+02:00)
Asia/Tokyo	Japan Standard Time (UTC+09:00)

Kubernetes
Docker

Parameters:

xdm.timezone
```
xdm:
  timezone: Europe/Berlin
```

Parameters:

TZ environment variable

services:
  core-server:
    environment:
      - TZ=Europe/Berlin
  dataflow-server:
    environment:
      - TZ=Europe/Berlin
  web-ui:
    environment:
      - TZ=Europe/Berlin

Password encryption

XDM stores users and passwords in the Admin Database to authorize against remote systems like databases or REST APIs. For example, they are used during a task execution to authorize against source and/or target database systems. For security reasons, a seed is used to encrypt (e.g. DB credentials) passwords when storing them in the admin database.

The property xdm.core.security.seed defines this seed and is required for secure operation. If the property is missing or blank, the core startup is aborted with a clear security error.

For secure configuration, the seed should follow this policy:

minimum length: 12 characters
at least one uppercase letter
at least one lowercase letter
at least one digit
at least one special character

If the seed is configured but does not meet the policy, the core continues to start and writes a security warning to the log.

After the seed is configured, XDM encrypts existing unencrypted passwords after a restart of the XDM core service. All newly created passwords are encrypted automatically.

If the seed is changed, all previously stored passwords become invalid.

Startup behavior:

If xdm.core.security.seed is missing or blank, the core startup is aborted with a security error.
If xdm.core.security.seed is configured but weak, the core starts and writes a warning to the log.

Kubernetes
Docker

Parameters:

Password Seed or Secret (only one has to be set)

xdm:
  security:
    passwordSeed: <your-seed>
    secret: <your-secret>

Parameters:

xdm.core.security.seed

services:
  core-server:
    environment:
      - xdm.core.security.seed=<your-seed>

  dataflow-server:
    environment:
      - xdm.core.security.seed=<your-seed>