Define the Startup Configuration
This document explains how to define the Semarchy xDM startup configuration.
Introduction
The Startup Configuration is the bootstrap configuration required for Semarchy xDM to start. It includes:
-
The Repository Datasources configuration, required for Semarchy xDM to access the repository database.
-
Optionally, the Secrets Management configuration, used to encrypt secrets using key management services or store secrets in secrets managers.
The startup configuration is composed of properties, set using the following methods:
For the first startup of the Semarchy xDM application, you also need to configure a Setup Token you will use to authenticate and create the repository. The setup token must be passed as an environment variable.
Required Configuration
The startup configuration is required for Semarchy xDM to start and connect the repository database. Make sure to prepare that configuration before installing or starting the application. Similarly, the Setup Token will be requested to access Semarchy xDM for the first login. Make sure to set this token before the first access. |
Create a Startup Configuration
This section explains how to quickly create a simple startup configuration using environment variables.
To create a startup configuration:
-
Edit the file containing the application server environment variables:
-
If you run Tomcat as a process, edit the
setenv.sh
(Linux/Unix) orsetenv.bat
(Windows). This file is located in the/bin
sub-folder in the Apache Tomcat installation folder. -
If you run Tomcat as a service, edit the
/etc/default/tomcat9
file. -
For other application servers, refer to the server documentation.
-
-
Append to this file the samples below to create the startup configuration environment variables.
-
Adapt the variable values to your configuration, using the database name, user names, and passwords that you entered when configuring the database schemas.
Make sure to select the sample corresponding to your database technology and your server operating system. |
Startup Configuration for PostgreSQL
# Repository datasource
export XDM_REPOSITORY_DRIVER=org.postgresql.Driver
export XDM_REPOSITORY_URL=jdbc:postgresql://localhost:5432/postgres
export XDM_REPOSITORY_USERNAME=repository_user
export XDM_REPOSITORY_PASSWORD=repository_password
# Repository read-only datasource credentials
export XDM_REPOSITORY_READONLY_USERNAME=repository_readonly_user
export XDM_REPOSITORY_READONLY_PASSWORD=repository_readonly_password
# Setup Token
export SEMARCHY_SETUP_TOKEN=mySecretValue
rem Repository datasource
set XDM_REPOSITORY_DRIVER=org.postgresql.Driver
set XDM_REPOSITORY_URL=jdbc:postgresql://localhost:5432/postgres
set XDM_REPOSITORY_USERNAME=repository_user
set XDM_REPOSITORY_PASSWORD=repository_password
rem Repository read-only datasource credentials
set XDM_REPOSITORY_READONLY_USERNAME=repository_readonly_user
set XDM_REPOSITORY_READONLY_PASSWORD=repository_readonly_password
rem Setup Token
set SEMARCHY_SETUP_TOKEN=mySecretValue
Startup Configuration for SQL Server
# Repository datasource
export XDM_REPOSITORY_DRIVER=com.microsoft.sqlserver.jdbc.SQLServerDriver
export XDM_REPOSITORY_URL=jdbc:sqlserver://localhost:1433;databaseName=REPOSITORY
export XDM_REPOSITORY_USERNAME=repository_user
export XDM_REPOSITORY_PASSWORD=repository_password
# Repository read-only datasource credentials
export XDM_REPOSITORY_READONLY_USERNAME=repository_readonly_user
export XDM_REPOSITORY_READONLY_PASSWORD=repository_readonly_password
# Setup Token
export SEMARCHY_SETUP_TOKEN=mySecretValue
rem Repository datasource
set XDM_REPOSITORY_DRIVER=com.microsoft.sqlserver.jdbc.SQLServerDriver
set XDM_REPOSITORY_URL=jdbc:sqlserver://localhost:1433;databaseName=REPOSITORY
set XDM_REPOSITORY_USERNAME=repository_user
set XDM_REPOSITORY_PASSWORD=repository_password
rem Repository read-only datasource credentials
set XDM_REPOSITORY_READONLY_USERNAME=repository_readonly_user
set XDM_REPOSITORY_READONLY_PASSWORD=repository_readonly_password
rem Setup Token
set SEMARCHY_SETUP_TOKEN=mySecretValue
Startup Configuration for Oracle
# Repository datasource
export XDM_REPOSITORY_DRIVER=oracle.jdbc.OracleDriver
export XDM_REPOSITORY_URL=jdbc:oracle:thin:@localhost:1521:XE
export XDM_REPOSITORY_USERNAME=repository_user
export XDM_REPOSITORY_PASSWORD=repository_password
# Repository read-only datasource credentials
export XDM_REPOSITORY_READONLY_USERNAME=repository_readonly_user
export XDM_REPOSITORY_READONLY_PASSWORD=repository_readonly_password
# Set the current schema of the readonly user to the repository
export XDM_REPOSITORY_READONLY_CONNECTIONINITSQL="ALTER SESSION SET CURRENT_SCHEMA = '$XDM_REPOSITORY_USERNAME'"
# Setup Token
export SEMARCHY_SETUP_TOKEN=mySecretValue
rem Repository datasource
set XDM_REPOSITORY_DRIVER=oracle.jdbc.OracleDriver
set XDM_REPOSITORY_URL=jdbc:oracle:thin:@localhost:1521:XE
set XDM_REPOSITORY_USERNAME=repository_user
set XDM_REPOSITORY_PASSWORD=repository_password
rem Repository read-only datasource credentials
set XDM_REPOSITORY_READONLY_USERNAME=repository_readonly_user
set XDM_REPOSITORY_READONLY_PASSWORD=repository_readonly_password
rem Set the current schema of the readonly user to the repository
set XDM_REPOSITORY_READONLY_CONNECTIONINITSQL='ALTER SESSION SET CURRENT_SCHEMA = repository_user'
rem Setup Token
set SEMARCHY_SETUP_TOKEN=mySecretValue
When the startup configuration is defined, you can move to the next step and deploy Semarchy xDM.
You can also read the next sections to learn more about the startup configuration contents and configuration methods.
Startup Configuration Contents
This section details the contents of the startup configuration.
Repository Connections
In the samples above, two connections to the repository are defined:
-
The Repository Datasource, with credentials allowing to read from and write into the repository schema.
-
The Repository Read-Only Datasource, with credentials allowing to read a subset of the tables stored in the repository schema. This datasource is used mainly by xDM Discovery to browse the profiles.
The properties used to configure these datasources are listed in the Startup Configuration Reference
Setup Token
In the samples, the SEMARCHY_SETUP_TOKEN
environment variable contains the Setup Token.
The Setup Token is a value required the first time you connect to Semarchy xDM to create or upgrade the repository. This token is used as an authentication method to let you configure the administrator login and password.
After the initial installation or upgrade, the setup token is no longer used and can be removed from the configuration.
Secrets Management
The startup configuration may also include the secrets management configuration:
-
Multiple Key Management Services (KMS) to encrypt secrets stored in the repository, with one of them set as the Current KMS.
-
Multiple Secrets Managers to access secrets (passwords, keys, etc) stored in external secrets managers such as AWS Secrets Manager, Azure Key Vault, or Google Cloud Secret Manager.
The Secrets Management configuration properties are detailed in Secrets Management.
Startup Configuration Methods
This section explains the methods to set the startup configuration properties.
The startup configuration is composed of a set of Configuration Properties with their values. Properties names are lowercase strings with dots delimiters. They start with the xdm.
prefix.
For example:
-
xdm.config.file
configures the location of the default configuration file. -
xdm.secrets.internal.kms.current
configures the alias of the current key management service used to encrypt secrets.
There are three ways to set the configuration properties:
Java System Properties
With this method, configuration properties are set in the startup command of the Java Machine running Semarchy xDM, using the following syntax:
-D<property.name>=<value>
For example:
-Dxdm.secrets.internal.kms.current=awscorporate
For Tomcat, you can set such a property in the <tomcat>/bin/setenv.sh|bat
file, as shown below:
CATALINA_OPTS="$CATALINA_OPTS -Dxdm.secrets.internal.kms.current=awscorporate"
Environment Variables
With this method, variables are set in the environment running the java machine.
The variable names are derived from the java properties, uppercased and with all the dots replaced by userscore characters. For example, the xdm.secrets.internal.kms.current
property value will be set in the XDM_SECRETS_INTERNAL_KMS_CURRENT
environment variable.
The following examples illustrate how to set this configuration property in the environment.
# Set environment variable: Unix/Linux
export XDM_SECRETS_INTERNAL_KMS_CURRENT=awscorporate
# See the variable value
# echo $XDM_SECRETS_INTERNAL_KMS_CURRENT
rem Set environment variable: Windows
set XDM_SECRETS_INTERNAL_KMS_CURRENT "awscorporate"
rem See the variable value
rem echo %XDM_SECRETS_INTERNAL_KMS_CURRENT%
Semarchy xDM automatically recognizes the configuration properties from the environment variable.
The /samples folder in the Semarchy xDM package that you downloaded contains complete configuration samples using environment variables, in the setenv_sample.sh and setenv_sample.bat files.
|
Configuration File
You can define startup configuration properties in a single properties file.
When starting, Semarchy xDM looks by default for a <USER_HOME>/.xdm/config.properties
properties file containing the startup configuration. You can also change the location of this file using the xdm.config.file
configuration property.
Property (Environment Variable) | Description |
---|---|
|
Startup configuration file path. Defaults to |
<tomcat_home>/bin/setenv.sh
.# Append this line to setenv.sh
CATALINA_OPTS="$CATALINA_OPTS -Dxdm.config.file=/etc/xdm/dev_001.properties"
When running Tomcat as a process, you can quickly configure the startup configuration using this properties file.
To create the startup configuration:
-
In the Home directory of the user starting the application server running Semarchy xDM, create a folder named
.xdm
. -
Create in that folder a
config.properties
file, using one of the samples below.
Configuration File Samples
The following samples define the repository datasources using a configuration file.
# Repository datasource
xdm.repository.driver=org.postgresql.Driver
xdm.repository.url=jdbc:postgresql://localhost:5432/postgres
xdm.repository.username=repository_user
xdm.repository.password=repository_password
# Repository read-only datasource credentials
xdm.repository.readonly.username=repository_readonly_user
xdm.repository.readonly.password=repository_readonly_password
# Repository datasource
xdm.repository.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
xdm.repository.url=jdbc:sqlserver://localhost:1433;databaseName=REPOSITORY
xdm.repository.username=repository_user
xdm.repository.password=repository_password
# Repository read-only datasource credentials
xdm.repository.readonly.username=repository_readonly_user
xdm.repository.readonly.password=repository_readonly_password
# Repository datasource
xdm.repository.driver=oracle.jdbc.OracleDriver
xdm.repository.url=jdbc:oracle:thin:@localhost:1521:XE
xdm.repository.username=repository_user
xdm.repository.password=repository_password
# Repository read-only datasource credentials
xdm.repository.readonly.username=repository_readonly_user
xdm.repository.readonly.password=repository_readonly_password
# Set the current schema of the readonly user to the repository
xdm.repository.readonly.connectioninitsql=ALTER SESSION SET CURRENT_SCHEMA = repository_user
The /samples folder in the Semarchy xDM package that you downloaded contains a complete configuration property file sample named config_sample.properties .
|
Configuration Methods Priority
The value of each property is read in the following order:
-
From the configuration file,
-
From the corresponding environment variable, overriding the configuration file value,
-
From the Java system property, overriding the configuration file and/or environment variable values.
For example, if a property is set in the configuration file and as a Java system property, then the Java system property is used.
The different methods for the startup configuration are useful for each type of setup:
|