Advanced Parameters

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

The advanced parameters of the Kafkorama Gateway are described below.

RunAsUser

If kafkorama is an existing unprivileged user, you can configure Kafkorama Gateway to run under this user by adding the following to the configuration:

RunAsUser = kafkorama

To bind to privileged ports such as 80 or 443, you must start Kafkorama Gateway as root.

PublishAllowFromAddressList

If this parameter is set, Kafkorama Gateway will accept message publications only from clients running on the IP addresses specified in this list.

If the parameter is not configured, message publication is allowed from any client — provided the client is permitted by the entitlement rules you define (see the Entitlement parameter).

PublishAllowFromAddressList = 192.168.5.23, 10.0.0.0/24

Native.Ssl

This parameter accepts two values: true or false. If set to true, Kafkorama Gateway will use the BoringSSL library for TLS/SSL support. BoringSSL typically offers better performance in terms of memory and CPU usage compared to the default Java implementation. While this difference may be negligible for small or medium deployments, it is recommended to enable Native.Ssl for large-scale deployments with millions of users.

MaxCachedMessagesPerSubject

For each subject, Kafkorama Gateway maintains a dedicated in-memory cache. Messages are continuously removed from the cache, but each message remains cached either:

• up to the maximum number of messages defined by this parameter, or
• until the number of seconds specified by CacheExpireTime has passed — whichever condition is met first.

CacheExpireTime

For each subject, Kafkorama Gateway maintains a dedicated in-memory cache. Messages are continuously removed from the cache, but each message remains cached either:

• at least for the number of seconds defined by this parameter, or
• up to the maximum number of messages defined by MaxCachedMessagesPerSubject

SnapshotExpireTime

The Kafkorama Gateway stores a snapshot message in memory for each subject. By default, these snapshot messages are retained indefinitely. You can use this parameter to define a time limit, expressed in seconds, for how long snapshot messages should be kept in memory. This setting is particularly useful in environments where new subjects are frequently added but no longer updated after a certain point. Without an expiration time, snapshot messages from inactive subjects could accumulate and lead to memory issues.

Workgroups

To optimize scalability on multi-core systems, users are split into separate groups, each managed by its own thread. This parameter sets the number of such groups. If not specified, it defaults to the number of CPU cores. Changing this value is generally not recommended unless for advanced tuning.

IoThreads

This parameter controls how many threads are allocated for handling I/O. By default, it matches the number of CPU cores. Changing this value is generally not recommended unless for advanced tuning.

Stats.LogInterval

This parameter controls how frequently various performance and usage statistics are written to the log. The minimum allowed value is 5 seconds.

The log entries have the following format:

[timestamp] [S] [INFO] [STATS] { 
  connectedSessions,
  connectedSessionsWeb,
  connectedSessionsMobile,
  connectedSessionsDesktop,
  sessionConnectionsPerSecond,
  sessionDisconnectionsPerSecond,
  inPublishMessagesPerSecond,
  outPublishMessagesPerSecond,
  inBytesPerSecond,
  outBytesPerSecond,
  clientInPublishMessagesPerSecond,
  connectRateRecoverySuccessPerSecond,
  connectRateRecoveryFailPerSecond,
  clientPublishFailedPerSecond }

MaxBatchingSpace

Batching groups multiple messages together before sending them in a single I/O operation to the client — either after a size threshold MaxBatchingSpace or a time threshold MaxBatchingTime is reached.

By default, batching by size is disabled. When enabled, Kafkorama Gateway sends messages in batches rather than individually. This reduces the number of I/O operations and improves performance, especially for use cases with high-frequency updates — such as multiple messages per second per subject across most subjects.

The diagram below illustrates the difference between message flow without batching (left) and with batching (right):

MaxBatchingTime

This parameter defines the maximum time to wait before sending a batch, regardless of its size.

See MaxBatchingSpace for an overview of batching.

By default, batching by time is disabled. Enable this parameter only for use cases with high-frequency updates — such as multiple messages per second per subject across most subjects.

SslProtocols

For Java 8, the default enabled protocols are TLSv1.2, TLSv1.1, and TLSv1. You can override this default list by configuring this SslProtocols parameter.

For example, to allow only the TLSv1.2 protocol:

SslProtocols = TLSv1.2

CipherListEnabled

Use this parameter to enable one or more supported ciphers not enabled by default. For example:

CipherListEnabled = \
  TLS_DHE_RSA_WITH_AES_128_CBC_SHA, \
  TLS_DHE_DSS_WITH_AES_128_CBC_SHA

CipherListExcluded

Use this parameter to exclude one or more ciphers enabled by default. For example:

CipherListEnabled = \
  TLS_DHE_RSA_WITH_AES_128_CBC_SHA, \
  TLS_DHE_DSS_WITH_AES_128_CBC_SHA

MaxMessageSize

This parameter defines the maximum total size (in bytes) of a message — including protocol overhead — that Kafkorama Gateway will accept.

If a message sent by a client exceeds the configured MaxMessageSize (or its default value), Kafkorama Gateway will reject it, and the client will receive a status notification with the code NOTIFY_MESSAGE_SIZE_LIMIT_EXCEEDED.

MaxBandwidthRate

This parameter limits the outbound bandwidth used by Kafkorama Gateway to deliver messages to clients. The rate is specified in bytes per second (B/s). If set to 0 (the default), no bandwidth limitation is enforced.

This setting is especially useful when the message throughput temporarily exceeds the available network bandwidth. For example, if Kafkorama Gateway is running on a machine with a 1 Gbps (125 MB/s) network interface and needs to deliver a burst of 1250 MB of messages to many clients, setting:

MaxBandwidthRate = 1000000000

will ensure the messages are sent steadily over ~10 seconds, preventing system overload and maintaining low message latency. Without this cap, the kernel’s socket buffers could become saturated, impacting system performance.

Beyond burst scenarios, this parameter also acts as a safeguard — intentional or accidental — from exceeding the available network bandwidth capacity.

For most cases, it is recommended to set this value to match the maximum available outbound bandwidth of the system.

Extension.Audit.Access

Set this parameter to log4j to enable access logging using the pre-installed Log4j audit extension located in the addons folder of your Kafkorama Gateway installation.

Extension.Audit.Cache

Set this parameter to log4j to enable cache logging using the pre-installed Log4j audit extension located in the addons folder of your Kafkorama Gateway installation.

Extension.Audit.Message

Set this parameter to log4j to enable message logging using the pre-installed Log4j audit extension located in the addons folder of your Kafkorama Gateway installation.

Extension.Audit.Stats

Set this parameter to log4j to enable stats logging using the pre-installed Log4j audit extension located in the addons folder of your Kafkorama Gateway installation.