Network

We recommend the central Port configuration in bpc.env and the configuration in Secure Connection (TLS/HTTPS).

TL;DR

<OPENSEARCH-CONFIG-DIR>/opensearch.yml
http.port: 9200
transport.tcp.port: 9300
os-bpc-plugin.websocket.port: 9203
karaf/etc/de.virtimo.bpc.core.cfg
de.virtimo.bpc.core.opensearch.port = 9200
karaf/etc/org.apache.karaf.shell.cfg
sshPort = 8101
karaf/etc/org.apache.karaf.management.cfg
rmiRegistryPort = 1099
rmiServerPort = 44444
karaf/etc/org.ops4j.pax.web.cfg
org.osgi.service.http.port = 8181
org.osgi.service.http.port.secure = 8282
org.osgi.service.http.enabled = false
org.osgi.service.http.secure.enabled = true
bpc.env

  • Unix-based systems (bpc.env.sh)

  • Windows-based systems (bpc.env.cmd)

export ORG_APACHE_KARAF_SHELL_SSHPORT=8101
export ORG_APACHE_KARAF_MANAGEMENT_RMIREGISTRYPORT=1099
export ORG_APACHE_KARAF_MANAGEMENT_RMISERVERPORT=44444
export ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_PORT=8181
export ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_PORT_SECURE=8282
export DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_PORT=9200
export DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_TRANSPORT_PORT=9300
export DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_WEBSOCKET_PORT=9203

export ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_ENABLED=false
export ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_SECURE_ENABLED=true
SET ORG_APACHE_KARAF_SHELL_SSHPORT=8101
SET ORG_APACHE_KARAF_MANAGEMENT_RMIREGISTRYPORT=1099
SET ORG_APACHE_KARAF_MANAGEMENT_RMISERVERPORT=44444
SET ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_PORT=8181
SET ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_PORT_SECURE=8282
SET DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_TRANSPORT_PORT=9300
SET DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_WEBSOCKET_PORT=9203
SET DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_PORT=9200
SET DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_OPENSEARCH_HOSTS=https://localhost:9200

SET ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_ENABLED=false
SET ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_SECURE_ENABLED=true

To run multiple separate instances on a single server, various Parameters must be configured. These adjustments may also be necessary for other reasons (already occupied Ports, etc.) and will be described in more detail here.

It is recommended to use only encrypted connections. See also: Secure Connection (TLS/HTTPS).

Relevant configuration parameters

In general, the following parameters must be taken into account:

  • OpenSearch Ports (default 9200–9300 and 9300–9400; see below for explanation)

  • OpenSearch cluster ID (default opensearch_virtimo)

  • Karaf BPC instance name (default BPC)

  • Karaf Ports for:

    • HTTP (default 8181)

    • HTTPS (default 8282)

    • SSH (default 8101)

    • JMX/RMI Port (Default 1099, 44444)

Configuration Details

The Karaf parameters listed below can also be set via the Karaf console (syntax: config:property-set -p de.virtimo.bpc.core CONFIGKEY CONFIGVALUE). It is recommended to set these parameters as environment variables in bpc.env. Alternatively, configuration via the Karaf configuration files in the etc directory is also described here.

It is strongly recommended not to make configuration changes directly in the Karaf configuration files under <BPC-INSTALL-DIR>/karaf/etc/, but to use the central bpc.env file instead. During updates of the BPC or Karaf installation, files in the etc directory may be overwritten or replaced with new default versions. Environment variables defined via bpc.env persist across version upgrades, simplifying automated deployment and maintenance. For more details on syntax and usage, see Overriding Values in etc Files.

OpenSearch Ports

The OpenSearch Ports must be adjusted in both OpenSearch and Karaf so that both products can communicate with each other again.

By default, OpenSearch defines two port ranges (9200–9300 and 9300–9400) and selects the lowest unused port in each range. This must be changed and set to a fixed Port, since Karaf only queries exactly one Port anyway; otherwise, multiple instances of the same OpenSearch might be running unknowingly (and they’ll work, too, since each new instance simply grabs the next Port and then says, “Hey cluster, I’m one of you, talk to me”).

OpenSearch itself reads its port configuration from the file <OPENSEARCH-CONFIG-DIR>/opensearch.yml. Therefore, it is sufficient to define these three values with the new Ports at the end of the file:

http.port: 9200
transport.tcp.port: 9300
# Default: 9203
os-bpc-plugin.websocket.port: 9204

To ensure that Karaf can reach OpenSearch on the new Port, this Port must also be specified in the BPC configuration file <Karaf_Root>/etc/de.virtimo.bpc.core.cfg (value of the http.port Parameter from the OpenSearch configuration):

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

BPC/Karaf establishes a WebSocket connection to OpenSearch (value of the os-BPC-plugin.websocket.port parameter from the OpenSearch configuration). The port does not need to be configured in BPC, as it is queried by OpenSearch at runtime.

Both services must then be restarted.

BPC-Instance-Name

The session cookie is stored without port information—that is, for a host regardless of the port used (according to RFC6265, “cookies for a given host are shared across all the Ports on that host”). As a result, one would attempt to use a session across multiple instances. BPC correctly recognizes that it does not recognize this session (from another BPC instance) and discards it. Consequently, it is not possible to log in to multiple instances on a single host simultaneously. There is now an instance name used as a prefix for the session information, allowing multiple sessions within a single browser to be managed for the same target host.

It is recommended to set the instance name in bpc.env:

bpc.env

  • Unix-based systems (bpc.env.sh)

  • Windows-based systems (bpc.env.cmd)

export DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_NAME="BPC"
SET DE_VIRTIMO_BPC_CORE_DE_VIRTIMO_BPC_CORE_NAME=BPC

Alternatively, set the following key in the file <Karaf_Root>/etc/de.virtimo.bpc.core.cfg:

de.virtimo.bpc.core.cfg
de.virtimo.bpc.core.name = BPC

Then please restart Karaf.

Karaf Ports

Karaf uses different protocols and ports for communication. Among other things, it provides an SSH, an HTTP, and an HTTPS interface. A JMX/RMI interface is also available and should be adjusted if the Ports are already in use.

The note about restarting Karaf after any Port changes should no longer apply here.

SSH Port

Karaf provides an SSH interface for configuration and analysis purposes on both Linux and Windows. By default, this is accessible on Port 8101.

It is recommended to configure the port and host in bpc.env:

bpc.env

  • Unix-based systems (bpc.env.sh)

  • Windows-based systems (bpc.env.cmd)

export ORG_APACHE_KARAF_SHELL_SSHPORT="8101"
export ORG_APACHE_KARAF_SHELL_SSHHOST="0.0.0.0"
SET ORG_APACHE_KARAF_SHELL_SSHPORT=8101
SET ORG_APACHE_KARAF_SHELL_SSHHOST=0.0.0.0

Alternatively, this can be changed in the file <Karaf_Root>/etc/org.apache.karaf.shell.cfg using the following settings:

org.apache.karaf.shell.cfg
sshPort = 8101
sshHost = 0.0.0.0

To prevent the server from being accessible from the outside, you can bind sshHost to localhost (127.0.0.1) or another local interface (0.0.0.0 = global/all IPv4 addresses of the host).

HTTP(S) Port

The ports for HTTP and HTTPS can be configured in bpc.env:

bpc.env

  • Unix-based systems (bpc.env.sh)

  • Windows-based systems (bpc.env.cmd)

export ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_PORT="8181"
export ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_PORT_SECURE="8282"
export ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_ENABLED="false"
export ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_SECURE_ENABLED="true"
SET ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_PORT=8181
SET ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_PORT_SECURE=8282
SET ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_ENABLED=false
SET ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_SECURE_ENABLED=true

Alternatively, they are defined in the file <Karaf_Root>/etc/org.ops4j.pax.web.cfg:

org.ops4j.pax.web.cfg
org.osgi.service.http.port = 8181
org.osgi.service.http.port.secure = 8282
org.osgi.service.http.enabled = false
org.osgi.service.http.secure.enabled = true

Here, the respective protocol can also be enabled or disabled separately (e.g., to allow only HTTPS).

JMX/RMI Ports

The ports for the JMX/RMI interface can be configured in bpc.env:

bpc.env

  • Unix-based systems (bpc.env.sh)

  • Windows-based systems (bpc.env.cmd)

export ORG_APACHE_KARAF_MANAGEMENT_RMIREGISTRYPORT="1099"
export ORG_APACHE_KARAF_MANAGEMENT_RMISERVERPORT="44444"
export ORG_APACHE_KARAF_MANAGEMENT_RMIREGISTRYHOST="0.0.0.0"
export ORG_APACHE_KARAF_MANAGEMENT_RMISERVERHOST="0.0.0.0"
SET ORG_APACHE_KARAF_MANAGEMENT_RMIREGISTRYPORT=1099
SET ORG_APACHE_KARAF_MANAGEMENT_RMISERVERPORT=44444
SET ORG_APACHE_KARAF_MANAGEMENT_RMIREGISTRYHOST=0.0.0.0
SET ORG_APACHE_KARAF_MANAGEMENT_RMISERVERHOST=0.0.0.0

Alternatively, they are configured in the file <Karaf_Root>/etc/org.apache.karaf.management.cfg using the following parameters:

org.apache.karaf.management.cfg
rmiRegistryPort = 1099
rmiServerPort = 44444
rmiRegistryHost = 0.0.0.0
rmiServerHost = 0.0.0.0

To make JMX/RMI available only locally, you can (similar to SSH) bind the listener from the global 0.0.0.0 to any local interface (e.g., 127.0.0.1).

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