Central configuration file

It is possible, for example, to adjust the BPC’s network ports and memory via a central bpc.env file (bpc.env.sh for Unix systems and bpc.env.cmd for Windows systems). This file must be located in the same directory (INSTALLATIONSVERZEICHNIS) as Karaf and OpenSearch.

We recommend making your own configurations recognizable by comments and possibly documenting them directly. This makes subsequent updates easier.

Illustration 1. Folder structure with bpc.env file

You will find the appropriate bpc.env file for your version on the download page.

To update an existing bpc.env, please refer to the Update Guide.

Unix systems (bpc.env.sh)
Windows systems (bpc.env.cmd)

#!/bin/bash

# This file should be placed in the same directory as Karaf and OpenSearch.
# It will automatically be loaded by Karaf and OpenSearch on startup.

### Java Home
# The 'java_home_path_setter.sh' (inubit installer) gets called to set the Java home path.
# In case the file does not exist or you want to use a different Java home, you can overwrite it here.
#export JAVA_HOME="<path to jvm>"


### RAM

# OpenSearch
# To avoid multiple xmx/xms params in your process list you could remove these params from opensearch/config/jvm.options
export OPENSEARCH_JAVA_OPTS="$OPENSEARCH_JAVA_OPTS -Xms1g -Xmx1g"

# Karaf
export EXTRA_JAVA_OPTS="$EXTRA_JAVA_OPTS -Xms128m -Xmx512m"


### Network

# To change all ports by an offset you can change the PORT_OFFSET. For example PORT_OFFSET=10000 will add 10000 to all ports.
# So the port 8181 will be 18181.
export PORT_OFFSET=0

export ORG_APACHE_KARAF_SHELL_SSHPORT=$(($PORT_OFFSET + 8101))
export ORG_APACHE_KARAF_MANAGEMENT_RMIREGISTRYPORT=$(($PORT_OFFSET + 1099))
export ORG_APACHE_KARAF_MANAGEMENT_RMISERVERPORT=$(($PORT_OFFSET + 4444))
export ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_PORT=$(($PORT_OFFSET + 8181))
export ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_PORT_SECURE=$(($PORT_OFFSET + 8282))
export DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_PORT=$(($PORT_OFFSET + 9200))
export DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_TRANSPORT_PORT=$(($PORT_OFFSET + 9300))
export DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_WEBSOCKET_PORT=$(($PORT_OFFSET + 9203))

# enable/disable HTTP (org.osgi.service.http.enabled)
#export ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_ENABLED=false
# enable/disable HTTPS (org.osgi.service.http.secure.enabled)
#export ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_SECURE_ENABLED=true

#### OpenSearch Config Directory
# by default, the configuration directory is in opensearch/config
# You can change the config directory by setting this env variable (rel to OpenSearch-Home BPC_DIR/opensearch/)
# export OPENSEARCH_PATH_CONF=../opensearch_config

### pax-jdbc Features to install

# Usually they must be installed from the Karaf Shell, e.g.: feature:install pax-jdbc-oracle
#
# You can automate this by providing the pax-jdbc features to install by a comma separated list.
#
# Some of these pax-jdbc features try to download and install jdbc-drivers for you.
# This is not always the driver version you need. In case you provide your own jdbc-driver,
# then mark those entries with (*). Then those pax-jdbc features get installed when
# your provided jdbc-driver is already installed as a wrapped bundle.

#export KARAF_PAX_JDBC_FEATURES_TO_INSTALL='pax-jdbc-oracle (*), pax-jdbc-sqlite, pax-jdbc-mssql (*), pax-jdbc-mariadb (*)'


### Set custom jetty configuration, like HTTP headers

# You can modify the jetty configuration and keep them active during Karaf updates.
# copy the KARAF/etc/jetty.xml to the same folder as bpc.env and uncomment the following line
# export ORG_OPS4J_PAX_WEB_ORG_OPS4J_PAX_WEB_CONFIG_FILE=\${karaf.base}/../jetty.xml

### Karaf Log
# Changes for KARAF/etc/de.virtimo.bpc.decanter.appender.opensearch.cfg
# See also https://docs.virtimo.net/de/bpc-docs/latest/core/admin/operation/karaf_log.html

#export DE_VIRTIMO_BPC_DECANTER_APPENDER_OPENSEARCH_ENABLED=true
#export DE_VIRTIMO_BPC_DECANTER_APPENDER_OPENSEARCH_CLEANUPPERIODINMINUTES=60
#export DE_VIRTIMO_BPC_DECANTER_APPENDER_OPENSEARCH_DELETEENTRIESOLDERTHAN=7 days ago


### Override Karaf Properties

# You can override any configuration using either environment variables or system properties.
# You can use PID_PROPERTY=VALUE syntax for environment variable
# For instance, the following statement will override value sshPort in etc/org.apache.karaf.shell.cfg:
# export ORG_APACHE_KARAF_SHELL_SSHPORT=8102
# see also https://karaf.apache.org/manual/latest/#_environment_variables_system_properties

### Additional Karaf JVM Options
export EXTRA_JAVA_OPTS="$EXTRA_JAVA_OPTS -Djava.security.properties=../custom.java.security"
### Additional OpenSearch JVM Options
export OPENSEARCH_JAVA_OPTS="$OPENSEARCH_JAVA_OPTS -Djava.security.properties=../custom.java.security"

### Keystore and Truststore

# it is recommended to move your customized Keystore and Truststore files out of the Karaf and OpenSearch folders

# Default Karaf locations:
#   ./bpc/karaf/etc/virtimo/ssl/virtimo_keystore.jks
#   ./bpc/karaf/etc/virtimo/ssl/virtimo_truststore.jks

# Default OpenSearch locations:
#   ./bpc/opensearch/config/virtimo/ssl/virtimo_keystore.jks
#   ./bpc/opensearch/config/virtimo/ssl/virtimo_truststore.jks

# Recommended new locations:
#   ./bpc/ssl/virtimo_keystore.jks
#   ./bpc/ssl/virtimo_truststore.jks

# afterwards uncomment the following for Karaf
#export ORG_OPS4J_PAX_WEB_ORG_OPS4J_PAX_WEB_SSL_KEYSTORE=../ssl/virtimo_keystore.jks
#export ORG_OPS4J_PAX_WEB_ORG_OPS4J_PAX_WEB_SSL_TRUSTSTORE=../ssl/virtimo_truststore.jks

# and create a symbolic link for OpenSearch
#cd bpc/opensearch/config/virtimo && ln -s ../../../ssl ssl

@echo off

rem This file should be placed in the same directory as Karaf and OpenSearch.
rem It will automatically be loaded by Karaf and OpenSearch on startup.

rem *****************
rem *** Java Home ***
rem *****************
rem The 'java_home_path_setter.cmd' (inubit installer) gets called to set the Java home path.
rem In case the file does not exist or you want to use a different Java home, you can overwrite it here.

rem set JAVA_HOME=<path to jvm>

rem ***********
rem *** RAM ***
rem ***********

rem *** OpenSearch ***
rem To avoid multiple xmx/xms params in your process list you could remove these params from opensearch/config/jvm.options
SET OPENSEARCH_JAVA_OPTS=%OPENSEARCH_JAVA_OPTS% -Xms1g -Xmx1g

rem *** Karaf ***
SET EXTRA_JAVA_OPTS=%EXTRA_JAVA_OPTS% -Xms128m -Xmx512m

rem ***************
rem *** Network ***
rem ***************

rem To change all ports by an offset you can change the PORT_OFFSET. For example PORT_OFFSET=10000 will add 10000 to all ports.
rem So the port 8181 will be 18181.
SET PORT_OFFSET=0

SET /a ORG_APACHE_KARAF_SHELL_SSHPORT=%PORT_OFFSET% + 8101
SET /a ORG_APACHE_KARAF_MANAGEMENT_RMIREGISTRYPORT=%PORT_OFFSET% + 1099
SET /a ORG_APACHE_KARAF_MANAGEMENT_RMISERVERPORT=%PORT_OFFSET% + 4444
SET /a ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_PORT=%PORT_OFFSET% + 8181
SET /a ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_PORT_SECURE=%PORT_OFFSET% + 8282
SET /a DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_PORT=%PORT_OFFSET% + 9200
SET /a DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_TRANSPORT_PORT=%PORT_OFFSET% + 9300
SET /a DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_WEBSOCKET_PORT=%PORT_OFFSET% + 9203

rem enable/disable HTTP (org.osgi.service.http.enabled)
rem SET ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_ENABLED=false
rem enable/disable HTTPS (org.osgi.service.http.secure.enabled)
rem SET ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_SECURE_ENABLED=true

rem *** OpenSearch Config Directory ***
rem by default, the configuration directory is in opensearch\config
rem You can change the config directory by setting this env variable (rel to OpenSearch-Home BPC_DIR\opensearch)
rem SET OPENSEARCH_PATH_CONF=..\opensearch_config

rem ****************************
rem pax-jdbc Features to install
rem ****************************

rem Usually they must be installed from the Karaf Shell, e.g.: feature:install pax-jdbc-oracle

rem You can automate this by providing the pax-jdbc features to install by a comma separated list.

rem Some of these pax-jdbc features try to download and install jdbc-drivers for you.
rem This is not always the driver version you need. In case you provide your own jdbc-driver,
rem then mark those entries with (*). Then those pax-jdbc features get installed when
rem your provided jdbc-driver is already installed as a wrapped bundle.
rem SET KARAF_PAX_JDBC_FEATURES_TO_INSTALL=pax-jdbc-oracle (*), pax-jdbc-sqlite, pax-jdbc-mssql (*), pax-jdbc-mariadb (*)

rem ****************************
rem Set custom jetty configuration, like HTTP headers
rem ****************************

rem You can modify the jetty configuration and keep them active during Karaf updates.
rem copy the KARAF/etc/jetty.xml to the same folder as bpc.env and uncomment the following line
rem SET ORG_OPS4J_PAX_WEB_ORG_OPS4J_PAX_WEB_CONFIG_FILE=${karaf.base}/../jetty.xml

rem ****************************
rem Karaf Log
rem ****************************
rem Changes for KARAF/etc/de.virtimo.bpc.decanter.appender.opensearch.cfg
rem See also https://docs.virtimo.net/de/bpc-docs/latest/core/admin/operation/karaf_log.html

rem SET DE_VIRTIMO_BPC_DECANTER_APPENDER_OPENSEARCH_ENABLED=true
rem SET DE_VIRTIMO_BPC_DECANTER_APPENDER_OPENSEARCH_CLEANUPPERIODINMINUTES=60
rem SET DE_VIRTIMO_BPC_DECANTER_APPENDER_OPENSEARCH_DELETEENTRIESOLDERTHAN=7 days ago

rem ****************************
rem Override Karaf Properties
rem ****************************

rem You can override any configuration using either environment variables or system properties.
rem You can use PID_PROPERTY=VALUE syntax for environment variable
rem For instance, the following statement will override value sshPort in etc/org.apache.karaf.shell.cfg:
rem SET ORG_APACHE_KARAF_SHELL_SSHPORT=8102
rem see also https://karaf.apache.org/manual/latest/#_environment_variables_system_properties

:: ****************************
:: Additional Karaf JVM Options
:: ****************************
SET EXTRA_JAVA_OPTS=%EXTRA_JAVA_OPTS% -Djava.security.properties=..\custom.java.security

:: ****************************
:: Additional OpenSearch JVM Options
:: ****************************
SET OPENSEARCH_JAVA_OPTS=%OPENSEARCH_JAVA_OPTS% -Djava.security.properties=..\custom.java.security

rem ****************************
rem Keystore and Truststore
rem ****************************

rem it is recommended to move your customized Karaf Keystore and Truststore files out of the Karaf and OpenSearch folders

rem Default Karaf locations:
rem   ./bpc/karaf/etc/virtimo/ssl/virtimo_keystore.jks
rem   ./bpc/karaf/etc/virtimo/ssl/virtimo_truststore.jks

rem Default OpenSearch locations:
rem   ./bpc/opensearch/config/virtimo/ssl/virtimo_keystore.jks
rem   ./bpc/opensearch/config/virtimo/ssl/virtimo_truststore.jks

rem Recommended new locations:
rem  ./bpc/ssl/virtimo_keystore.jks
rem  ./bpc/ssl/virtimo_truststore.jks

rem afterwards uncomment the following for Karaf
rem SET ORG_OPS4J_PAX_WEB_ORG_OPS4J_PAX_WEB_SSL_KEYSTORE=../ssl/virtimo_keystore.jks
rem SET ORG_OPS4J_PAX_WEB_ORG_OPS4J_PAX_WEB_SSL_TRUSTSTORE=../ssl/virtimo_truststore.jks

rem and create a symbolic link for OpenSearch (start the shell as administrator)
rem cd bpc && rmdir /s opensearch\config\virtimo\ssl && mklink /J opensearch\config\virtimo\ssl ssl

The Karaf Service Wrapper ignores this file. It is recommended to use Service without a wrapper (see Services).

Java runtime environment

The environment variable JAVA_HOME can also be set in the file. This ensures that OpenSearch and Karaf use the Java version defined there. In the delivery state, JAVA_HOME is not set in the bpc.env files.

Working memory (RAM)

The allocation of working memory for OpenSearch and Karaf can be set by setting the variables OPENSEARCH_JAVA_OPTS and EXTRA_JAVA_OPTS.

JVM system properties

System properties can also be set via the variables OPENSEARCH_JAVA_OPTS for OpenSearch and EXTRA_JAVA_OPTS for Karaf. Such system properties are set as follows -D<name>=<wert>.

If, for example, the standard time zone of the JVM (Java Virtual Machine) is to be set to 'Europe/Berlin', then -Duser.timezone=Europe/Berlin is added to the existing value of the variable.

Example to set a system property for OpenSearch

Unix systems
Windows systems

export OPENSEARCH_JAVA_OPTS="$OPENSEARCH_JAVA_OPTS -Xms1g -Xmx1g -Duser.timezone=Europe/Berlin"

SET OPENSEARCH_JAVA_OPTS=%OPENSEARCH_JAVA_OPTS% -Xms1g -Xmx1g -Duser.timezone=Europe/Berlin

Example to set a system property for Karaf

Unix systems
Windows systems

export EXTRA_JAVA_OPTS="$EXTRA_JAVA_OPTS -Xms128m -Xmx512m -Duser.timezone=Europe/Berlin"

SET EXTRA_JAVA_OPTS=%EXTRA_JAVA_OPTS% -Xms128m -Xmx512m -Duser.timezone=Europe/Berlin

Network Ports

Within the file, all ports can be changed at once by setting the PORT_OFFSET variable. Alternatively, individual Ports can also be set by setting individual variables.

We recommend setting up Secure connection (TLS/HTTPS) and deactivating the HTTP port.

Keystore and Truststore

It is recommended to store the keystore and truststore files outside of Karaf and OpenSearch in a central location. This makes future updates easier, as OpenSearch and Karaf can be updated without having to repeat the configuration of TLS.

Default location Karaf

INSTALLATIONSVERZEICHNIS/karaf/etc/virtimo/ssl

Default location OpenSearch

OPENSEARCH_CONFIG_VERZEICHNIS/virtimo/ssl

Java Security Settings

An additional file for java.security.properties is referenced in bpc.env via the environment variable EXTRA_JAVA_OPTS. This file is called custom.java.security and should be located in the same directory as bpc.env. The security.properties can be overwritten in the file custom.java.security. This makes it possible, for example, to overwrite DNS settings or TLS settings.For example, it is possible to change DNS settings or TLS Parameters. The provided custom.java.security already contains some settings for hardening TLS connections.

Default custom.java.security

#networkaddress.cache.ttl=10
#networkaddress.cache.negative.ttl=10

# Extended JDK (25) default configuration
# The last line differs from the default configuration,
# We use the modern configuration by Mozilla (https://github.com/mozilla/server-side-tls) as guidelines.
jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, DTLSv1.0, RC4, DES, \
    MD5withRSA, DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL, \
    ECDH, TLS_RSA_*, rsa_pkcs1_sha1 usage HandshakeSignature, \
    ecdsa_sha1 usage HandshakeSignature, dsa_sha1 usage HandshakeSignature, \
    X448, secp521r1, SHA1

The properties refer to the default settings of the JVM. It is possible that Karaf or OpenSearch offer different configuration options and do not take the JVM configuration into account.

Oracle database

If an Oracle database is used, the location of the tnsnames.ora configuration file can be specified. The configuration is carried out via the environment variable oracle.net.tns_admin, which is inserted in KARAF_SYSTEM_OPTS, e.g.:

Unix systems
Windows systems

export KARAF_SYSTEM_OPTS="$KARAF_SYSTEM_OPTS -Dlog4j2.formatMsgNoLookups=true -Doracle.net.tns_admin=/etc/"

SET KARAF_SYSTEM_OPTS=%KARAF_SYSTEM_OPTS% -Dlog4j2.formatMsgNoLookups=true -Doracle.net.tns_admin=C:\oracle\network\admin

Install Karaf 'pax-jdbc' features automatically

Make sure that the module PAX JDBC Feature Installer module is installed.

After copying the JDBC driver to be used into the [karaf]/deploy directory, you normally have to install the pax-jdbc features manually via the Karaf shell (see also Databases). Example: feature:install pax-jdbc-oracle

When executing the feature:install command, some of the pax-jdbc features attempt to download and install JDBC drivers for you. However, this is not always the driver version you need.

The installation can be automated via the environment variable KARAF_PAX_JDBC_FEATURES_TO_INSTALL by specifying the pax-jdbc features to be installed in a comma-separated list.

If you provide your own JDBC drivers via the [karaf]/deploy directory, then mark these entries with (*). The associated pax-jdbc features are then only installed if your supplied JDBC driver is already available as a so-called wrapped bundle.

Example:

In this scenario, Oracle, SQLite, Microsoft SQL Server and MariaDB databases are to be accessed from the BPC. The necessary pax-jdbc features are to be installed automatically for this.

Unix systems
Windows systems

export KARAF_PAX_JDBC_FEATURES_TO_INSTALL='pax-jdbc-oracle (*), pax-jdbc-sqlite, pax-jdbc-mssql (*), pax-jdbc-mariadb (*)'

SET KARAF_PAX_JDBC_FEATURES_TO_INSTALL=pax-jdbc-oracle (*), pax-jdbc-sqlite, pax-jdbc-mssql (*), pax-jdbc-mariadb (*)

Here pax-jdbc-sqlite is installed immediately, if not already done.
pax-jdbc-oracle, pax-jdbc-mssql and pax-jdbc-mariadb are not installed until the associated JDBC driver is available from Karaf as a so-called wrapped bundle.

If only one database is to be accessed, then only one pax-jdbc feature is to be installed. If no database needs to be accessed, the environment variable does not need to be set.

adapt jetty.xml

If you need to adapt jetty.xml, e.g. to change HTTP header, you should proceed as follows.

Copy the existing file INSTALLATIONSVERZEICHNIS/karaf/etc/jetty.xml to INSTALLATIONSVERZEICHNIS
Make the necessary adjustments to INSTALLATIONSVERZEICHNIS/jetty.xml
Set the environment variable ORG_OPS4J_PAX_WEB_ORG_OPS4J_PAX_WEB_CONFIG_FILE via Central configuration file so that the changed jetty.xml is taken into account
- Unix systems
- Windows systems
export ORG_OPS4J_PAX_WEB_ORG_OPS4J_PAX_WEB_CONFIG_FILE=\${karaf.base}/../jetty.xml
SET ORG_OPS4J_PAX_WEB_ORG_OPS4J_PAX_WEB_CONFIG_FILE=${karaf.base}/../jetty.xml

Your INSTALLATIONSVERZEICHNIS should then look like this:

Illustration 2. Folder structure with changed jetty.xml

Overwrite values of etc files

The Karaf configuration settings are distributed across various files in the [karaf]/etc directory. When updating Karaf, it is easy to lose track of what has previously been adjusted and what needs to be updated in the new version.
Simply overwriting all of these configuration files is not expedient, as any newly added options may not be set correctly.

Environment variables can be used to overwrite specific values in the configuration files. The name of the environment variable must be based on the following structure: (NAME DER KONFIGURATIONSDATEI)_(NAME DER OPTION).
Please note the capitalization and replace spaces and special characters with underscores.

Example 1: Setting the SSH Ports

Excerpt from the file [karaf]/etc/org.apache.karaf.shell.cfg:

#
# Via sshPort and sshHost you define the address you can login into Karaf.
#
sshPort = 8101

The value of the option sshPort should be set to 18202 via environment variable:

Unix systems
Windows systems

export ORG_APACHE_KARAF_SHELL_SSHPORT=18102

SET ORG_APACHE_KARAF_SHELL_SSHPORT=18102

Example 2: Setting the OpenSearch Port

Excerpt from the file [karaf]/etc/de.virtimo.bpc.core.cfg:

en.virtimo.bpc.core.opensearch.port = 9200

The value of the option de.virtimo.bpc.core.opensearch.port should be set to 19200 via environment variable:

Unix systems
Windows systems

export DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_PORT=19200

SET DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_PORT=19200

Keywords: