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. |
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
### 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
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 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
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, angepasste Keystore- und Truststore-Dateien aus den Karaf- und OpenSearch-Ordnern zu verschieben.
Standardort Karaf |
|
Standardort OpenSearch |
|
Empfohlener neuer Ort |
|
Nachdem sich die angepassten virtimo_keystore.jks
und virtimo_truststore.jks
Dateien im neuen Ort befinden sind noch kleine Anpassungen für Karaf und OpenSearch erforderlich.
Diese sind in der jeweiligen bpc.env
Datei beschrieben.
Java Security Settings
Die Umgebungsvariable EXTRA_JAVA_OPTS
zeigt nun auf die Datei custom.java.security, die im selben Verzeichnis liegen sollte wie die bpc.env.
In der Datei custom.java.security können die security.properties überschrieben werden, wie z.B. die unten aufgeführten DNS Einstellungen.
Diese Einstellungen wirken sich nur auf Karaf aus.
networkaddress.cache.ttl=10 networkaddress.cache.negative.ttl=10
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
nachINSTALLATIONSVERZEICHNIS
-
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ändertejetty.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:
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 |
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