Core Parameters

Explore core options to fine-tune the performance and behavior of Kafkorama Gateway.

The core parameters of the Kafkorama Gateway are described below.

LicenseKey

The license key is a string composed of numbers and letters. It is issued by Kafkorama for evaluation, development, or production use of the Kafkorama Gateway. To obtain a license key, please contact us.

Memory

This parameter sets the maximum heap size (-Xmx) of the Java Virtual Machine (JVM) running the Kafkorama Gateway, expressed in megabytes (MB).

For example, to allocate 512 megabytes of heap memory, use:

Memory = 512 MB

In a production environment it is recommended to use at least 8192 MB (i.e. 8 GB) or more, depending on the data load and the number of simultaneous client connections.

Listen

This parameter defines one or more network addresses where Kafkorama Gateway listens for incoming client connections. Each address must be in one of the following forms:

• IP Address:Port
• DNS Name:Port
• [IPv6 Address]:Port (IPv6 addresses are enclosed in square brackets)

Examples

Listen = 192.168.1.1:80, push.example.com:8800

If the port is omitted, the default port 80 is used.

• Specifying a concrete IP address binds the Gateway only to that address.
• Using the wildcard address * (e.g., *:80) binds the Gateway to all available interfaces.

ListenEncrypted

This parameter follows the same conventions as the Listen parameter, with the exception that if a port is not specified, the default port 443 is used.

KeyStore

The keystore file must be configured using absolute paths. For example:

The keystore must contain a SSL certificate for each address used in the configuration of the following parameters:

Adding a Self-Signed Certificate to the Keystore

Run one of the following commands depending on how the address is specified in the configuration:

You will be asked to set a password for the keystore if it does not exist, or enter the existing password if it already exists. This password must be provided to the KeyStorePassword parameter.

Adding a CA-Signed Certificate to the Keystore

To securely configure a Kafkorama Gateway for the domain push.example.com, you need:

ListenEncrypted = push.example.com:443
KeyStore = /my/path/mykeystore.jks
KeyStorePassword = mypassword

Step 1: Prepare Certificate Files

You should have the following:

• Private Key: push.example.com.key
• CSR (Certificate Signing Request): push.example.com.csr
• Signed Certificate: push.example.com.crt
• Intermediate Certificate (optional): intermediary.crt

If you have an intermediate certificate, chain it with the signed certificate:

cat intermediary.crt push.example.com.csr >> push.example.com.crt

Step 2: Convert to PKCS#12 Format

openssl pkcs12 -export \
  -in push.example.com.crt \
  -inkey push.example.com.key \
  -out push.example.com.pkcs12 \
  -name push.example.com \
  -passout pass:mypassword

Step 3: Import into JKS Keystore

keytool -importkeystore \
  -srckeystore push.example.com.pkcs12 \
  -srcstoretype PKCS12 \
  -srcstorepass mypassword \
  -srcalias "push.example.com" \
  -destkeystore mykeystore.jks \
  -deststoretype JKS \
  -deststorepass mypassword \
  -destalias "push.example.com"

Verify the keystore contents:

keytool -list -keystore mykeystore.jks -storepass mypassword

Using a Wildcard CA-Signed Certificate

To run two Kafkorama Gateway instances with push1.example.com and push2.example.com:

ListenEncrypted = push1.example.com:443
KeyStore = /my/path/mykeystore.jks
KeyStorePassword = mypassword

ListenEncrypted = push2.example.com:443
KeyStore = /my/path/mykeystore.jks
KeyStorePassword = mypassword

Import the same wildcard certificate with different aliases:

keytool -importkeystore \
  -srckeystore wildcard.example.com.pkcs12 \
  -srcstoretype PKCS12 \
  -srcstorepass mypassword \
  -srcalias "wildcard.example.com" \
  -destkeystore mykeystore.jks \
  -deststoretype JKS \
  -deststorepass mypassword \
  -destalias "push1.example.com"

Repeat for push2.example.com:

keytool -importkeystore \
  -srckeystore wildcard.example.com.pkcs12 \
  -srcstoretype PKCS12 \
  -srcstorepass mypassword \
  -srcalias "wildcard.example.com" \
  -destkeystore mykeystore.jks \
  -deststoretype JKS \
  -deststorepass mypassword \
  -destalias "push2.example.com"

Then verify:

keytool -list -keystore mykeystore.jks -storepass mypassword

KeyStorePassword

Set this parameter to the password that was defined when the keystore file was created (see KeyStore). The password is set during the creation of the keystore, typically when adding the first certificate entry, as explained in the KeyStore parameter description.

Monitor

This parameter specifies the monitoring interfaces to enable. Available options are: JMX, HTTP, and Prometheus. To enable multiple options, use a comma-separated list.

For example, to enable both JMX and Prometheus monitoring, use:

Monitor = JMX, Prometheus

MonitorUsername

MonitorPassword

MonitorJMX.Listen

The format of the address used by this parameter is the same as the format of the Listen parameter.

The jconsole utility (included with OpenJDK) can be used for JMX monitoring. Many commercial tools also support JMX with additional features like dashboards and persistence.

MonitorJMX.Authentication

Possible values: true or false. If set to true, clients must provide credentials defined by MonitorUsername and MonitorPassword.

MonitorJMX.Encryption

Possible values: true or false. If set to true, the JMX connection will be secured using SSL/TLS. This is strongly recommended when monitoring from untrusted networks (e.g., Internet).

The address used by MonitorJMX.Listen must have a certificate entry (with alias jmx) in the keystore defined by KeyStore.

Secure JMX Monitoring (Example using jconsole)

1. Create a truststore for the client:

keytool -export -alias jmx -keystore mykeystore.jks -rfc -file temp.cer
keytool -import -alias jmx -file temp.cer -keystore mytruststore.jks

2. Create a client keystore with alias jmx:

keytool -genkeypair -alias jmx -keyalg RSA -validity 3600 -keystore clientkeystore.jks

3. Connect with jconsole:

jconsole \
  -J-Djavax.net.ssl.keyStore=clientkeystore.jks \
  -J-Djavax.net.ssl.keyStorePassword=clientkeystore-password \
  -J-Djavax.net.ssl.trustStore=mytruststore.jks \
  -J-Djavax.net.ssl.trustStorePassword=mytruststore-password

MonitorHTTP.Listen

The format of the address used by this parameter is the same as the format of the Listen parameter.

Accessing the HTTP Monitoring Service

Example configuration:

Monitor = HTTP
MonitorUsername = admin
MonitorPassword = pass
MonitorHTTP.Listen = push.example.com:4000
MonitorHTTP.Authentication = true
MonitorHTTP.Encryption = false

Access the monitoring endpoint:

http://push.example.com:4000/stats?username=admin&password=pass

The response format:

<fieldname1>:<value1> <fieldname2>:<value2> ... <fieldnameN>:<valueN>

Available Stats

Each field is a statistic (Average, Max, Std Dev) applied to a metric (e.g., connected clients, messages/sec) for a specific period (e.g., current, last 15 mins, last hour, etc.).

XML and JSON Output

Append view=xml or view=json:

http://push.example.com:4000/stats?username=admin&password=pass&view=xml

Filters

You can add filters by GET parameters:

http://push.example.com:4000/stats?username=admin&password=pass&indicator=ConnectedSessions&statistic=MAX&period=Last.15.Minute

To get all averages:

http://push.example.com:4000/stats?username=admin&password=pass&statistic=AVG

Secure HTTP Monitoring

Enable encryption:

MonitorHTTP.Encryption = true

Use HTTPS:

https://push.example.com:4000/stats?username=user&password=pass

MonitorHTTP.Authentication

Values: true or false. If true, access requires credentials defined by MonitorUsername and MonitorPassword.

MonitorHTTP.Encryption

Values: true or false. If true, the HTTP monitoring endpoint is secured via SSL/TLS. The address defined in MonitorHTTP.Listen must be backed by a certificate in the KeyStore.

MonitorPrometheus.Listen

This parameter uses the same address format as Listen.

MonitorPrometheus.Authentication

Possible values: true or false. If set to true, access requires credentials specified by MonitorUsername and MonitorPassword.

MonitorPrometheus.Encryption

Possible values: true or false. If set to true, Prometheus clients will connect via SSL/TLS. This is strongly recommended when exposing the endpoint over insecure networks such as the Internet.

The address defined in MonitorPrometheus.Listen must have a certificate entry in the keystore configured by KeyStore. The alias for the certificate must be prometheus, as described in the KeyStore parameter documentation.

LogFolder

If not set, the default folder logs is used relative to the directory from which the Kafkorama Gateway is started.

You can specify an absolute path instead:

LogLevel

Available log levels:

• TRACE (most verbose)
• DEBUG
• INFO (recommended for production)
• WARN
• ERROR (least verbose)

LogRotateLimit

Accepted units:

• KB for kilobytes
• MB for megabytes
• GB for gigabytes

When a log file exceeds this size, it is rotated. Old log files are retained up to the number specified by LogRotateFileCount.

LogRotateTime

Time units:

• m for minutes
• h for hours
• D for days
• W for weeks
• M for months
• Y for years

Examples:

LogRotateTime = 1 D    # Rotate logs daily
LogRotateTime = 4 h    # Rotate logs every 4 hours

Takes precedence over LogRotateLimit.

LogRotateFileCount

When the number of rotated logs exceeds this limit, the oldest log file is deleted.

DocumentRoot

If not configured, the default folder html (relative to the directory from which Kafkorama Gateway is started) will be used.

Entitlement

To define which users of your application have access to which subjects, you can define one of the following Entitlement types:

• None allows any client to subscribe to and publish on any subject.
• Basic allows any client to subscribe to any subject. However, publication is allowed only from the clients which authenticate with the token defined by the parameter EntitlementAllowToken.
• JWT allows clients to subscribe and publish based on JWT tokens using Kafkorama JWT Authorization Add-on. To start using JWT authorization with Kafkorama Gateway, please refer to JWT Authorization add-on documentation.
• Custom allows you to define your own entitlement rules. You can use the Server Extensions API to build an extension for Kafkorama Gateway to authorize users to subscribe to or publish on certain subjects.
• Portal allows you to define your own entitlement using Kafkorama Portal. See also the parameters Portal.Url and Portal.Password.

EntitlementAllowToken

This parameter is used only when Entitlement is set to Basic.

Portal.Url

The Kafkorama Gateway periodically connects to your Kafkorama Portal at this HTTPS endpoint to retrieve configuration data for the Kafka cluster configurations defined in the portal, as well as entitlement-related information such as expired JWT tokens.

Portal.Password

Use this parameter to authenticate the periodic entitlement and Kafka configuration queries performed by the Kafkorama Gateway against your Kafkorama Portal instance.