Karaf

Karaf is one of the central system components for the BPC. It is an open source software of the Apache Software Foundation

The documentation of the software can be found here.

As part of the BPC installation a pre-configured variant of Apache Karaf is provided.

Configuration

Working memory (RAM)

The amount of allocated working memory is set via the environment variable EXTRA_JAVA_OPTS. This environment variable is also used when using the central configuration via bpc.en central configuration via bpc.env.sh is used.

Please also refer to the memory examples for the available hardware under System requirements

Console

The Karaf console can be used to easily query the current status of the system and to read out and adjust configurations.
See also Apache Karaf Documentation - Using the Console.

A Karaf console commands Cheat Sheet is available for particularly frequently used Karaf console commands.

Access

Access to the console is possible both locally and remotely. Authentication takes place via the Karaf user list.
The predefined admin role can log in, but comprehensive administrative tasks can only be performed in combination with other roles. These roles are combined in the predefined group g:admingroup.
Detailed information can be found under Apache Karaf Documentation - Security.

Karaf Client

A client for the console is located in the Karaf directory under bin/client (or bin/client.bat for Windows). This enables local and remote access to the console.

SSH

The Karaf console is also available directly via the SSH protocol. Unless otherwise configured (see Central configuration file), Port 8101 is available for this purpose.

External access via SSH

By default, SSH access to the host localhost is restricted. If it is necessary to make Karaf accessible via external connections, this can be done by adjusting the setting org.apache.karaf.shell.sshHost. The value 0.0.0.0 allows connections from all IP addresses.

The change can be made either via the configuration file KARAF_HOME/etc/org.apache.karaf.shell.cfg, the Karaf console or the central configuration file.

We recommend using the central configuration file. To do this, simply activate the line commented out by default:

Unix systems
Windows systems

bpc.env.sh

export ORG_APACHE_KARAF_SHELL_SSHHOST=0.0.0.0

bpc.env.cmd

SET ORG_APACHE_KARAF_SHELL_SSHHOST=0.0.0.0

For optimum security, always use the most restrictive settings that enable your workflow.

Access with private/public key procedure

Follow the steps below:

Creating the key pair:
Execute the following command to create a new key pair. Alternatively, you can also use an existing key pair.
ssh-keygen -t rsa -f karaf.id_rsa
Insert the public key in keys.properties.
The file keys.properties in the KARAF_HOME/etc directory allows you to assign an SSH key to a user. The user-key pairs are defined in the following format: user=key,role

keys.properties File with SSH public key

virtimo=<SSH-Public-Key>,_g_:admingroup
_g_\:admingroup = group,admin,manager,viewer,systembundles,ssh

If the syntax of the file is not adhered to, authentication is not possible and no connection can be established.
Make sure that the SSH public key does not contain any spaces.

SSH access requires the role ssh, which is not set by default.

Establish connection via SSH:
ssh -p 8101 -i ~/karaf.id_rsa virtimo@localhost

Access with username/password

As an alternative to the public/private key procedure, authentication can also be carried out using a user name and password. The file users.properties in the KARAF_HOME/etc directory is used for this purpose.

Follow the steps below:

Add user and password in users.properties: See Using users.properties for Karaf access.
Connect via SSH:
ssh -p 8101 -i ~/karaf.id_rsa karaf@localhost

For detailed information, see Apache Karaf Documentation - Security.

BPC-specific commands

See Karaf console commands for the BPC.

Tuning

See https://karaf.apache.org/manual/latest/#_tuning

Keywords: