12.15.100 12.14.100 12.13.100 12.12.100 12.11.100 12.10.100 12.09.110 12.09.100 12.08.130 12.08.110 12.08.100
12.15.100 12.14.100 12.13.100 12.12.100 12.11.100 12.10.100 12.09.110 12.09.100 12.08.130 12.08.110 12.08.100 English German

How to Configure the IGEL UMS for Automated Deployments Using Environment Variables or application.yml

You can configure the data source, UMS ID, and Distributed UMS settings of the IGEL Universal Management Suite (UMS) through environment variables or an application.yml file. These configuration sources support automated and repeatable deployments without requiring you to configure these settings manually in the UMS Administrator.

This article explains how to prepare the required values, configure the UMS on Linux or Windows, and understand the priority and limitations of the supported configuration sources.


Configuration Process Overview

You can provide UMS settings through environment variables, an application.yml file, or a combination of both. When the UMS Server starts, it evaluates each setting separately and uses the source with the highest priority. When the same setting is defined in more than one source, the UMS Server applies the value from the source with the higher priority.

Configuration Source

Priority

When to Use It

Environment variables

Highest

Use for automated deployments or when the deployment system supplies configuration values to the operating system.

application.yml

Second

Use when you want to maintain the UMS settings in a configuration file.

UMS Administrator

Lowest

Use for settings that are not defined through environment variables or application.yml.

The configuration process consists of the following stages:

  1. Prepare the data source values and UMS ID values on an existing UMS installation.

  2. Choose where to define each setting. You can use one source for all supported settings or use different sources for individual settings.

  3. Add the prepared values to the selected configuration source and apply to the UMS Server.

  4. The UMS Server loads each setting according to the configuration source priority.

Prepare Values for Environment Variables or application.yml

Before configuring the target UMS installation, prepare the required data source and UMS ID values on an existing, running UMS installation. The prepared values can then be supplied through environment variables or added to application.yml.

Use a Linux installation to generate the UMS ID configuration data because the required ums_id_collect_outputs.sh script is available only on Linux. You can use the generated values to configure a target UMS installation on Linux or Windows.

Prepare the Data Source Configuration

Prepare the following properties and values for setting up the data source via a configuration source:

Property

Value to Provide

url

Provide the JDBC connection string.

username

Provide the database user name.

password

Provide the encrypted database password.

Encrypt the database password by running umsadmin-cli enc encrypt in the UMS Administrator Command-Line Interface (CLI).

Example: sudo umsadmin-cli enc encrypt -p=<your password>

The command returns the encrypted password:

Encrypted: AESG---------------------------

driver-class-name

Provide the JDBC driver class name. The driver classes used by the implementation are defined in the driverClass property for the selected database type under /ums/rmcommons/src/de/igel/rm/db.

The following JDBC driver class names are available:

  • oracle.jdbc.driver.OracleDriver

  • com.microsoft.sqlserver.jdbc.SQLServerDriver

  • org.postgresql.Driver

  • org.apache.derby.client.ClientAutoloadedDriver

db-type

Provide the database type. The database types used by the implementation are defined in the cliName property in /ums/rmcommons/src/de/igel/rm/db/DBType.java

The following database types are available:

  • oracle

  • oracle-rac

  • mssql

  • mssql-c

  • mssql-adn

  • mssql-adk

  • mssql-cadn

  • mssql-cadk

  • az-sql-mi

  • az-sql-mi-pwd

  • postgre

  • derby

Example data source configuration:

url: jdbc:postgresql://db_ip_address:5432/db_name
username: db_user
password: <encrypted_database_password>
driver-class-name: org.postgresql.Driver
db-type: postgre

Prepare the UMS ID

  1. Create a new UMS ID by using one of the following methods:

  1. Register the UMS ID in the IGEL License Portal as described in Registering the UMS.

  2. On Linux, run the following script to generate the UMS ID configuration data:

    <installation_path>/rmadmin/ums_id_collect_outputs.sh
    

The log shows the path to the output directory:

[info] Config and artifacts are in:
<installation_path>/IGEL/RemoteManager/rmadmin/config/20251121T132813Z

The output directory contains files similar to the following:

drwx------ 2 root root            4096 Nov 21 14:28 .
drwxrwxr-x 4 root ums_tomcat_user 4096 Nov 21 14:28 ..
-rw------- 1 root root            5321 Nov 21 14:28 ums_id_config.ini
-rw-r--r-- 1 root root            1939 Nov 21 14:28 UMS_ID.crt
-rw------- 1 root root            3886 Nov 21 14:28 ums-id.ksbak
-rw------- 1 root root            5184 Nov 21 14:28 ums-id.ksbak.b64

The ums_id_config.ini file provides the following values for configuration through environment variables or application.yml:

Property

Description

ums_backup_file_name

Name of the backup file

ums_backup_file_value

Base64-encoded backup file

backup_file_password

Password entered when running ums_id_collect_outputs.sh

Configure the UMS Through application.yml

The paths referenced below reflect the default UMS installation directories:

  • Linux: /opt/IGEL/RemoteManager/

  • Windows: C:\Program Files\IGEL\RemoteManager\

If a custom installation directory was chosen during setup, replace the default path prefix with your custom directory path (for example, <custom_install_path>/rmguiserver/conf/appconfig/application.yml).

  1. After installing the UMS, stop the UMS Server.

  2. Access the application.yml file:

    • On Linux, open /opt/IGEL/RemoteManager/rmguiserver/conf/appconfig/application.yml.

    • On Windows, open C:\Program Files\IGEL\RemoteManager\rmguiserver\conf\appconfig\application.yml.

  3. Add the prepared values to application.yml in the following format:

    igel:
      datasource:
        url: jdbc:postgresql://db_ip_address:5432/db_name
        username: db_user
        password: <encrypted_database_password>
        driver-class-name: org.postgresql.Driver
        db-type: postgre
      ums-id:
        backup-file-name: UMS-External-ID
        backup-file-password: <backup_file_password_from_ums_id_config.ini>
        backup-file-value: <ums_backup_file_value_from_ums_id_config.ini>
      distributed-ums: true
    
  1. Start the UMS Server.

Configure the UMS Through Environment Variables

Define the prepared environment variables as shown in the following example:

IGEL_DATASOURCE_URL=jdbc:postgresql://db_ip_address:5432/db_name
IGEL_DATASOURCE_USERNAME=db_user
IGEL_DATASOURCE_DB_TYPE=postgre
IGEL_DATASOURCE_DRIVER=org.postgresql.Driver
IGEL_DATASOURCE_PASSWORD=<encrypted_database_password>
IGEL_DISTRIBUTED_UMS=false
IGEL_UMS_ID_BACKUP_VALUE=<ums_backup_file_value_from_ums_id_config.ini>
IGEL_UMS_ID_BACKUP_NAME=UMS-External-ID
IGEL_UMS_ID_BACKUP_PASSWORD=<backup_file_password_from_ums_id_config.ini>

Set the Environment Variables on Linux Before or After Installation

When setting up environment variables before UMS installation:

  1. Add the prepared environment variables to /etc/environment.

  2. Run the UMS installer.

When setting up environment variables after UMS is already installed:

  1. Add the prepared environment variables to /etc/environment.

  2. Restart the UMS service.

Use global environment variables instead of user-specific environment variables. The Linux pkexec utility used to run the UMS Administrator restricts the use of environment variables as a security measure.

Set the Environment Variables on Windows Before Installation

  1. Before installing the UMS, add each name-value pair to the Windows environment variables.

  2. Run the UMS installer.

Limitations of Environment Variable and application.yml Configuration

When a property is defined through a configuration source other than the UMS Administrator, you cannot change that property through the UMS Administrator or the UMS Administrator CLI.

UMS Administrator Application Limitations

The properties configured through environment variables or application.yml cannot be changed through the UMS Administrator. Attempts to change them result in the error messages shown in the table below:

Configured Setting

Restricted Action

Message Shown

Data source

Under Datasource > Datasource Configurations, the Add, Edit, and Delete buttons do not perform their associated actions.

Database already configured externally, therefore the configuration was disabled.

UMS ID

Under UMS ID Backup, Restore does not restore the backup file.

We already have external ums id configuration.

Distributed UMS

Under Distributed UMS > High Availability UMS > Distributed UMS, changing Enable Distributed UMS does not change the configuration.

Distributed UMS already configured externally, therefore the configuration was disabled.

UMS Administrator CLI Limitations

The properties configured through environment variables or application.yml cannot be changed through the UMS Administrator CLI. Attempts to change them result in the error messages shown in the table below:

Configured Setting

Restricted Command

Message Shown

Data source

umsadmin-cli db activate, umsadmin-cli db edit, and umsadmin-cli db delete do not perform their associated actions.

Error message: Database already configured externally, therefore the configuration was disabled.

UMS ID

umsadmin-cli licensing restore does not restore the backup file.

UMS ID is already configured externally.

Distributed UMS

umsadmin-cli server distributed does not change the configuration.

Distributed UMS already configured externally, therefore the configuration was disabled.