Zentrale Konfigurationsdatei

Es besteht die Möglichkeit, z.B. Netzwerk-Ports und Arbeitsspeicher des BPCs über eine zentrale bpc.env.sh-Datei anzupassen. Diese Datei muss im gleichen Verzeichnis (INSTALLATIONSVERZEICHNIS) wie Karaf und OpenSearch liegen.

Wir empfehlen, eigene Konfigurationen durch Kommentare erkenntlich zu machen und evtl. so direkt zu dokumentieren. Dies erleichtert folgende Updates.

Abbildung 1. Ordnerstruktur mit bpc.env Datei

Sie finden die jeweils für Ihre Version passende bpc.env Datei auf der Downloadseite.

Für das Update einer bestehenden bpc.env beachten Sie bitte den Update Guide.

Beispiel bpc.env.sh für UNIX Systeme

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


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

Beispiel bpc.env.cmd für Windows Systeme

@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


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

Der Karaf Service Wrapper ignoriert diese Datei. Es wird empfohlen, Service ohne Wrapper (siehe Services) zu nutzen.

Java Laufzeitumgebung

In der Datei kann auch die Umgebungsvariable JAVA_HOME gesetzt werden. Dies sorgt dafür, dass OpenSearch und auch Karaf die dort definierte Java-Version nutzen. Im Auslieferungszustand wird in den bpc.env Dateien JAVA_HOME nicht gesetzt.

Arbeitsspeicher (RAM)

Über das Setzen der Variablen OPENSEARCH_JAVA_OPTS und EXTRA_JAVA_OPTS kann die Zuweisung vor Arbeitsspeicher für OpenSearch und Karaf gesetzt werden.

Siehe dazu auch Systemanforderungen

Netzwerk Ports

Innerhalb der Datei können über das Setzen der PORT_OFFSET Variable alle Ports auf einmal geändert werden. Alternativ können auch einzelne Ports über das Setzen einzelner Variablen gesetzt werden.

Wir empfehlen, Sichere Verbindung (TLS/HTTPS) einzurichten und den HTTP-Port zu deaktivieren.

Keystore und Truststore

Es wird empfohlen die Keystore- und Truststore-Dateien außerhalb vom Karaf und OpenSearch, an einer zentralen Stelle, abzulegen. Dies erleichtert zukünftige Updates, da so OpenSearch und Karaf aktualisiert werden können, ohne dass die Konfiguration von TLS wiederholt werden muss.

Standardort Karaf

INSTALLATIONSVERZEICHNIS/karaf/etc/virtimo/ssl

Standardort OpenSearch

INSTALLATIONSVERZEICHNIS/opensearch/config/virtimo/ssl

Empfohlener neuer Ort

INSTALLATIONSVERZEICHNIS/ssl

Die bpc.env ist so anzupassen, dass der Karaf die Dateien findet und für OpenSearch ein passender Link angelegt wird. Der Link für OpenSearch ist leider nötig, da der Prozess nicht auf Dateien außerhalb seines Ordners zugreifen darf.

bpc.env.sh (Linux)

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

Link unter Linux anlegen

cd opensearch/config/virtimo && ln -s ../../../ssl ssl

bpc.env.cmd (Windows)

SET ORG_OPS4J_PAX_WEB_ORG_OPS4J_PAX_WEB_SSL_KEYSTORE=../ssl/virtimo_keystore.jks
SET ORG_OPS4J_PAX_WEB_ORG_OPS4J_PAX_WEB_SSL_TRUSTSTORE=../ssl/virtimo_truststore.jks

Link unter Windows anlegen

rmdir /s opensearch\config\virtimo\ssl && mklink /J opensearch\config\virtimo\ssl ssl

Für die Erstellung des Symlinks unter Windows sind Administrator-Rechte nötig.

Beachten Sie, dass bei dieser Konfiguration OpenSearch und Karaf dieselben Keystore und Truststore Dateien nutzen. Das bedeutet, dass darin alle nötigen Zertifikate mit den passenden Aliases abgelegt sein müssen, die für beide Systemkomponenten nötig sind.

Siehe auch: Sichere Verbindung (TLS/HTTPS)

Oracle-Datenbank

Falls eine Oracle-Datenbank genutzt wird, kann der Ort der tnsnames.ora-Konfigurationsdatei angegeben werden. Die Konfiguration erfolgt über die Umgebungsvariable oracle.net.tns_admin, welche in der KARAF_SYSTEM_OPTS eingefügt wird, z.B.:

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

etc stellt dabei den individuellen Ort der Datei dar.

Karaf 'pax-jdbc'-Features automatisch installieren

Stellen Sie sicher, dass das Modul PAX JDBC Feature Installer installiert ist.

Nach dem Kopieren des zu verwendenden JDBC-Treibers in das [karaf]/deploy-Verzeichnis müssen Sie normalerweise die pax-jdbc-Features über die Karaf-Shell händisch installieren (siehe auch Datenbanken). Beispiel: feature:install pax-jdbc-oracle

Bei der Ausführung des feature:install-Kommandos versuchen einige der pax-jdbc-Features, JDBC-Treiber für Sie herunterzuladen und zu installieren. Dies ist jedoch nicht immer die Treiberversion, die Sie benötigen.

Über die Umgebungsvariable KARAF_PAX_JDBC_FEATURES_TO_INSTALL kann die Installation automatisiert werden, indem Sie die zu installierenden pax-jdbc-Features in einer durch Kommata getrennten Liste angeben.

Wenn Sie über das [karaf]/depploy-Verzeichnis eigene JDBC-Treiber bereitstellen, dann markieren Sie diese Einträge mit (*). Dann werden die zugehörigen pax-jdbc-Features erst installiert, wenn Ihr mitgelieferter JDBC-Treiber bereits als sogenanntes Wrapped Bundle zur Verfügung steht.

Beispiel:

In diesem Szenario sollen vom BPC auf Oracle, SQLite, Microsoft SQL Server und MariaDB Datenbanken zugegriffen werden. Dafür sollen die notwendigen pax-jdbc Features automatisch installiert werden.

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

Hier wird pax-jdbc-sqlite sofort installiert, falls noch nicht geschehen.
pax-jdbc-oracle, pax-jdbc-mssql und pax-jdbc-mariadb werden hingegen erst installiert, wenn der zugehörige JDBC-Treiber vom Karaf als sogenanntes Wrapped Bundle zur Verfügung steht.

Wenn nur auf eine Datenbank zugegriffen werden soll, dann ist auch nur ein zu installierendes pax-jdbc Feature anzugeben. Falls auf keine Datenbank zugegriffen werden muss, dann muss die Umgebungsvariable auch nicht gesetzt werden.

jetty.xml anpassen

Wenn Sie die jetty.xml anpassen müssen, um z.B. HTTP Header zu ändern, sollten Sie wie folgt vorgehen.

Kopieren Sie die vorhandene Datei INSTALLATIONSVERZEICHNIS/karaf/etc/jetty.xml nach INSTALLATIONSVERZEICHNIS
Führen Sie die nötigen Anpassungen an INSTALLATIONSVERZEICHNIS/jetty.xml durch
Setzen Sie die Umgebungsvariable ORG_OPS4J_PAX_WEB_ORG_OPS4J_PAX_WEB_CONFIG_FILE über die Zentrale Konfigurationsdatei damit die geänderte jetty.xml berücksichtigt wird
- 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

Anschließend sollte Ihr INSTALLATIONSVERZEICHNIS wie folgt aussehen:

Abbildung 2. Ordnerstruktur mit geänderter jetty.xml

Werte von etc-Dateien überschreiben

Die Konfigurationseinstellungen des Karaf sind im Verzeichnis [karaf]/etc auf diverse Dateien verteilt. Bei einem Karaf-Update geht leicht der Überblick verloren, was zuvor angepasst und in der neuen Version wieder nachgezogen werden muss.
Ein einfaches Überschreiben all dieser Konfigurationsdateien ist nicht zielführend, da somit evtl. neu hinzugekommene Optionen ggf. nicht korrekt gesetzt sind.

Über Umgebungsvariablen können spezifische Werte in den Konfigurationsdateien überschrieben werden. Dabei muss sich der Name der Umgebungsvariable an folgendem Aufbau orientieren: (NAME DER KONFIGURATIONSDATEI)_(NAME DER OPTION).
Bitte dabei die Großschreibung beachten und Leer- und Sonderzeichen durch Unterstriche ersetzen.

Siehe auch Karaf Dokumentation.

Zur Verdeutlichung siehe Beispiel 1: Setzen des SSH Ports und Beispiel 2: Setzen des OpenSearch Ports.

Die gesetzten Werte stehen zur Laufzeit zur Verfügung und werden nicht in die jeweiligen Konfigurationsdateien geschrieben. Über die Karaf-Shell können Sie sich per config:list die momentan gesetzten Werte anzeigen lassen.

Beispiel 1: Setzen des SSH Ports

Auszug aus der Datei [karaf]/etc/org.apache.karaf.shell.cfg:

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

Der Wert der Option sshPort soll per Umgebungsvariable auf 18202 gesetzt werden:

export ORG_APACHE_KARAF_SHELL_SSHPORT=18102

Beispiel 2: Setzen des OpenSearch Ports

Auszug aus der Datei [karaf]/etc/de.virtimo.bpc.core.cfg:

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

Der Wert der Option de.virtimo.bpc.core.opensearch.port soll per Umgebungsvariable auf 19200 gesetzt werden:

export DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_PORT=19200

Keywords: