Central configuration file

You can configure settings such as 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 marking your own configurations with comments and, if necessary, documenting them directly in this way. This makes future updates easier.

Illustration 1. Folder structure with BPC.env file

You can find the BPC.env file appropriate for your version on the download page.

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

Example bpc.env.sh for UNIX systems

#!/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

### 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

Example bpc.env.cmd for Windows systems

@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 ****************************
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 the service without the wrapper (see Services).

Java Runtime Environment

The environment variable JAVA_HOME can also be set in this file. This ensures that both OpenSearch and Karaf use the Java version defined there. By default, JAVA_HOME is not set in the BPC.env files.

Memory (RAM)

By setting the variables OPENSEARCH_JAVA_OPTS and EXTRA_JAVA_OPTS, you can configure the memory allocation for OpenSearch and Karaf.

JVM System Properties

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

For example, if you want to set the default time zone of the JVM (Java Virtual Machine) to 'Europe/Berlin', add -Duser.timezone=Europe/Berlin to the existing value of the variable.

Example of setting a system property for OpenSearch

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

Example of setting a system property for Karaf

export 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 be configured by setting individual variables.

We recommend configuring Secure Connection (TLS/HTTPS) and disabling 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 simplifies future updates, as it allows OpenSearch and Karaf to be updated without having to reconfigure TLS.

Default location for Karaf

INSTALLATIONSVERZEICHNIS/karaf/etc/virtimo/ssl

Default location for OpenSearch

INSTALLATIONSVERZEICHNIS/opensearch/config/virtimo/ssl

Java Security Settings

In bpc.env, the environment variable EXTRA_JAVA_OPTS references an additional file for java.security.properties. This file is named custom.java.security and should be located in the same directory as bpc.env. In the file custom.java.security, the security.properties settings can be overridden. This makes it possible, for example, 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

# we use the recommended configuration by Mozilla (https://github.com/mozilla/server-side-tls)
jdk.tls.disabledAlgorithms=X448, secp521r1, SHA1, include jdk.disabled.namedCurves

These 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. Configuration is performed via the environment variable ` oracle.net.tns_admin`, which is added to ` KARAF_SYSTEM_OPTS `, for example: `

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

etc represents the specific location of the file.

Automatically install Karaf 'pax-jdbc' features

Ensure that the PAX JDBC Feature Installer module is installed.

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

When you run 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.

You can automate the installation using 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, mark these entries with ` `(*). In this case, the corresponding `pax-jdbc features will not be installed unless your provided JDBC driver is already available as a so-called wrapped bundle.

Example:

In this scenario, the BPC is to access Oracle, SQLite, Microsoft SQL Server, and MariaDB databases. To do this, the necessary pax-jdbc features should be installed automatically.

export 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 it hasn’t already been done.
pax-jdbc-oracle, pax-jdbc-mssql, and pax-jdbc-mariadb, on the other hand, are only installed once the corresponding JDBC driver is available from Karaf as a so-called wrapped bundle.

If you only need to access one database, then you only need to specify one pax-jdbc feature to install. If you do not need to access any database, then you do not need to set the environment variable.

Customize jetty.xml

If you need to customize jetty.xml—for example, to change HTTP Headers —follow these steps.

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

Afterward, your ` INSTALLATIONSVERZEICHNIS ` should look like this:

Illustration 2. Folder structure with modified ` jetty.xml

` == Overwrite values from etc files

Karaf’s configuration settings are distributed across various files in the ` [karaf]/etc ` directory. During a Karaf update, it’s easy to lose track of what was previously customized and needs to be reconfigured in the new version.
Simply overwriting all these configuration files is not advisable, as this may result in newly added options not being set correctly.

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

Example 1: Setting the SSH Port

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

#
# Using sshPort and sshHost, you define the address you can use to log in to Karaf.
#
sshPort = 8101

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

export ORG_APACHE_KARAF_SHELL_SSHPORT=18102

Example 2: Setting the OpenSearch port

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

de.Virtimo.BPC.core.opensearch.port = 9200

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

export DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_PORT=19200

Keywords: