Configuring INUBIT in the ibis.xml File

Configuration file

<SUITE-INSTALL-DIR>/inubit/server/ibis_root/conf/ibis.xml

<Properties version="4.1">
  <Property name="LocalMaintenanceMode" type="Boolean">false</Property>
  <Property name="Database" type="Map">
    <Property name="driverClass">org.h2.Driver</Property>
    <Property name="jdbcUrl">jdbc:h2:${ibis.root.directory}/ibis_data/database/ibis;MVCC=TRUE</Property>
    <!-- Encrypted password and/or user name
      To get your encrypted password and/or user name use the CLI client.
      Example:
        cd path/to/inubit_installation/server/process_engine/bin
        ./startcli.sh -\-encryptString myPassword
      Insert the encrypted password and/or user name as values into the corresponding
      property tags and set the
      attribute encrypted="false" to encrypted="true".
      Example:
        <Property name="user" type="EncryptedString" encrypted="true">AES-ZKEFCtfXeLAmGUdQ2zomyA==</Property>
        <Property name="password" type="Password" encrypted="true">AES-ZKEFCtfXeLAmGUdQ2zomyA==</Property>
    -->
    <Property name="user" type="EncryptedString" encrypted="false">sa</Property>
    <Property name="password" type="Password" encrypted="false">secret</Property>
    <Property name="socketTimeoutInMillisecs" type="Long">180000</Property>
    <Property name="checkoutTimeoutInMillisecs" type="Long">120000</Property>
    <Property name="driverProperties" type="Map"/>
    <Property name="minPoolSize" type="Integer">5</Property>
    <Property name="maxPoolSize" type="Integer">30</Property>
  </Property>
  <Property name="DataSourceLocation">java:/comp/env/jdbc/IBISDB</Property>
  <Property name="RuntimeDataBackupStore">FILE</Property>
  <Property name="RuntimeDataCacheXMXPercentage" type="Integer">25</Property>
  <!-- Retry happens based on number of retries configured below -->
  <Property name="noOfRetries" type="Integer">3</Property>
  <!-- Retry interval value should be given in milliseconds-->
  <Property name="retryInterval" type="Long">2000</Property>
  <Property name="MaxEntriesInMemoryLimit" type="Map">
    <Property name="Workflow_Data_Version" type="Integer">-1</Property>
    <Property name="Module_Data_Version" type="Integer">-1</Property>
  </Property>
  <Property name="indexEnabled" type="Boolean">false</Property>
</Properties>

Configuring the Database in the ibis.xml File

Usage

Set the parameters for database access.

Properties

  1. Database driver

    • Syntax: driverClass=<datanase-driver-class>

    • Name of the database driver class

  2. JDBC URL

    • Syntax: jdbcUrl=jdbc:<database>@<port>:<schema>

    • Database driver URL

      For MySQL before version 5.7, it is only possible to communicate over TLS 1.2 when adding the property enabledTLSProtocols=TLSv1.2 to the database URL.

  3. Username

    • user=<Username> encrypted="{true|false}

    • Possible values:

      • true: The specified username is encrypted.

      • false: The specified username is not encrypted and is replaced by the encrypted username the first time the server starts. The attribute encrypted="true" is set automatically.

        Refer to Encrypting Usernames and Passwords via CLI

  4. Password

    • Syntax: password=<password> encrypted="{true|false}"

    • Possible values:

      • true: The specified password is encrypted.

      • false: The specified password is not encrypted and is replaced by the encrypted password the first time the server starts. The attribute encrypted="true" is set automatically.

        Refer to Encrypting Usernames and Passwords via CLI

  5. Socket timeout

    • Syntax: socketTimeoutInMillisecs=<value>

    • For configuration of the timeout for the socket connection between the JDBC driver and database. The value determines both, the connect and read timeout. The default value is 180'000 ms (3 minutes).

  6. Connection timeout for connection pooling

    • Syntax: checkoutTimeoutInMillisecs=<value>

    • For configuration of the timeout for waiting for the provision of a database connection for the database connection pool. The default value is 120'000 ms (2 minutes).

  7. Number of database connections

    minPoolSize=5
maxPoolSize=30

    • These two parameters determine how many database connections must be used at a minimum as well as how many can be used simultaneously. The default values are 5 and 30.

  8. Remove abandoned database connections

    • Syntax: removeAbandoned="{true|false}"

    • Possible values:

      • true

        A database connection is removed once the timeout configured in the removeAbandonedTimeout property has expired.

      • false (default)

        Database connections are not removed even if they are not used for some time.

  9. Timeout to Remove abandoned database connections

    • Syntax: removeAbandonedTimeout=<value>

    • If the removeAbandoned property is set to true, a database connection is removed once the timeout in seconds configured in the removeAbandonedTimeout property has expired. By default, the removeAbandonedTimeout property is set to 21'600 seconds (6 hours).

      The value should be set to the longest running query your applications might have.

  10. Valid connection check

    • Syntax: CheckValidConnection="{true|false}"

    • Possible values:

      • true: In case of an invalid connection, the next connection from the pool is selected automatically.

        By default, this property is set to true.

      • false: To disable the property.

        When this property is enabled, the performance may be slightly affected.

  11. Database query retry and retry delay

    noOfRetries=3
retryInterval=2000

    • In case of cache database errors, the query execution can be retried for a number of times specified in noOfRetries. Each retry will happen after a delay of time specified in retryInterval (in milliseconds).

      For MSSQL deadlocks, the following applies:

      In case of frequent deadlocks in the MSSQL database, you can try to increase the number of retries and the delay between each retry.

      The default values for these properties for MSSQL are 3 retries and 2000 milliseconds retry interval.

Allow using more than one schema (for MySQL 8 only, not recommended)

  • Syntax: nullCatalogMeansCurrent="{true|false}"

  • If a database user has access to more than one schema: Add the extra parameter nullCatalogMeansCurrent=true to the database URL.

Limiting the Size of the Runtime Data Cache

Usage

Defines the maximum percentage of the JVM heap (-Xmx) that may be used for caching runtime data (message payloads and workflow variables) in memory. When the combined size of all cached entries exceeds this limit, or an individual entry is larger than 1 MB, the data is automatically written to disk instead of being kept in memory. The Process Engine continues to operate normally in this case. There is no error or data loss, but disk I/O increases.

Properties

  • Syntax: RuntimeDataCacheXMXPercentage=25

  • Default value: 25 (25% of the JVM heap)

  • Example:

    If the JVM is started with -Xmx4g (4 GB heap), 25% means approximately 1 GB is available for the runtime data cache.
    With -Xmx16g, the same 25% results in approximately 4 GB.

  • Recommendation:

    For systems with significantly more heap than the default 4 GB, increasing the value can reduce disk I/O and improve throughput. Increase the value gradually and monitor the cache utilization and garbage collection behavior, as the remaining heap must still be sufficient for all other Process Engine operations. Cache utilization can be monitored via JMX (MBean DataStore.Binary, attributes RuntimeDataCacheMaxSize and RuntimeDataCacheUtilization).

    Refer to Folder Structure for details on the swap directories used when the cache limit is exceeded.

Memory Mode for Runtime Data

Usage

Determines how runtime data of asynchronous workflow executions is persisted. This setting controls whether and where the Process Engine writes backup copies of in-flight asynchronous execution data so that workflows can be recovered after a restart or crash.

Synchronous execution data is not affected by this setting. Synchronous data uses its own local stores without backup; it can still be swapped to disk on memory pressure, but is not persisted for recovery (see Folder Structure).

Properties

  • Syntax: RuntimeDataBackupStore={FILE|DB}

  • Possible values:

    • FILE (default)

      Runtime data is persisted to the local file system.

      Use this setting for best performance. File-based persistence has lower overhead than database persistence.

    • DB

      Runtime data is persisted to the database (tables IBIS_RT_EXEC_DATA and IBIS_RT_OTHER_DATA).

      Use this setting when data durability is more important than performance.

Configuring Retry and Retry Delay for the Cache Database

Usage

Set the parameters for cache database access.

Properties

noOfRetries=3
retryInterval=2000

In case of cache database errors, the query execution can be retried for a number of times specified in noOfRetries. Each retry will happen after a delay of time specified in retryInterval (in milliseconds).

The default values are 3 retries and 2000 ms delay.

Configuring the Maintenance Mode

Usage

Configuring the maintenance mode of the Process Engine on startup.

Properties

  • Syntax: LocalMaintenanceMode={true|false}

  • Possible Values:

    • true

      The local maintenance mode is activated.

    • false

      The local maintenance mode is deactivated.

Configuring Memory for Version Data

Usage

This configuration limits the number of module and workflow version definitions (XML data) that the Process Engine keeps in its in-memory cache. The limit refers to the total number of version entries across all modules or workflows, not the number of modules/workflows themselves.

Example: A limit of 100 for Module_Data_Version means that at most 100 module-version combinations are kept in memory at the same time. If there are 20 modules with 5 versions each, all 100 entries fit in the cache. A 21st module’s versions would cause some of the existing entries to be evicted from memory.

Properties

<Property name="MaxEntriesInMemoryLimit" type="Map">
    <Property name="Workflow_Data_Version" type="Integer">-1</Property>
    <Property name="Module_Data_Version" type="Integer">-1</Property>
</Property>

  • Module_Data_Version: Maximum number of module version entries in the cache

  • Workflow_Data_Version: Maximum number of workflow version entries in the cache

Eviction behavior

When the cache reaches its configured limit, the underlying Infinispan cache implementation evicts entries to make room for new ones. Evicted entries are not lost: all version data is also stored in the database, so an evicted entry is automatically reloaded from the database on the next access. Setting a limit therefore does not affect the availability of version data, only the access speed for entries that are not currently in memory.

Possible Values

  • -1 (default): Cache capacity is unlimited. All accessed versions remain in memory indefinitely.

    With a large number of module and workflow versions, unlimited caching can lead to high memory consumption and out-of-memory situations.

  • 1..n: Cache capacity is limited to this number of entries. Adjust based on the system’s available memory and the number of versions typically accessed during operation.

Timestamp Indexing on Infinispan

Usage

Controls the indexing behavior for timestamp columns in Infinispan tables.

Properties

  • Syntax: indexEnabled={true|false}

  • Possible values:

    • true: Enables indexing of Infinispan tables.

    • false: Disables indexing of Infinispan tables.

By default, this property is set to false. This keeps an existing INUBIT system backwards compatible. Indexing must be explicitly switched on and the system can be monitored.

If the parameter is set to `false` after indexing is applied, it will not trigger deindexing, because indexing has already been activated.

If you want to drop the index from existing Infinispan tables, follow these steps:

  • Set the property to false in ibis.xml after shutting down the Process Engine:
    <Property name="indexEnabled" type="Boolean">false</Property>

  • Execute the appropriate SQL queries to drop the timestamp index from all ISPN tables based on your database type:

    • MariaDB/MySQL
      ALTER TABLE <Database Name>
      DROP INDEX <Database Name>_timestamp_index;

    • PostgreSQL
      DROP INDEX <Database Name>_timestamp_index;

    • Microsoft SQL
      DROP INDEX <Database Name>_timestamp_index ON <Database Name>;

    • Oracle
      DROP INDEX IDX_<Database Name>;

      Example: For a table named ISPN_EDI_RULES in MySQL/MariaDB:
      ALTER TABLE ISPN_EDI_RULES
      DROP INDEX ISPN_EDI_RULES_timestamp_index;

      These queries must be run on all the tables with the ISPN_ prefix.

Configuring the ClusterDebug

  • Syntax: ClusterDebug={true|false}

  • Possible values:

    • true

      The log level can be changed after booting in the Workbench via Administration → Logging → Trace.

      When the server is restarted, it logs again at the DEBUG log level because ClusterDebug is true.

    • false

      The log level can be changed after booting in the Workbench via Administration → Logging → Trace.

      When the server is restarted, it logs again at the ERROR log level because ClusterDebug is false.

Configuring the iterationCount

The PBKDF2 (Password Based Key Derivation Function 2) user account password encryption algorithm uses an iterationCount to determine the number of times the hash algorithm is applied during the key derivation process. The iterationCount in PBKDF2 represents the number of times a pseudorandom function (such as HMAC-SHA256) is applied to a password to derive a secure key. The default value for iterationCount in ibis.xml is 20000.

  1. Higher iterationCount: The hash function (such as HMAC-SHA256) is used more frequently during the key derivation process when the iterationCount is higher.

    Advantages:

    • Increased Security: Makes brute force and password cracking attempts more expensive for attackers.

    • Key Strengthening: The derived key is protected against precomputed attacks (like rainbow tables) because each derivation is linked to the unique salt and the number of iterations.

    Disadvantages:

    • Slow down response times

    • Decrease throughput

    • Cause a short term spike in CPU and disk use

  2. Lower iterationCount: The hash function is used less frequently when the iterationCount is lower.

    Advantages:

    Useful for low power devices or high traffic systems where speed is critical.

    Disadvantages:

    Decreased Security: Improves password cracking and brute force attacks quicker for attackers.

Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen