TBMQ configuration
HTTP server parameters
Section titled “HTTP server parameters”Shutdown type. Accepted values: graceful, immediate.
HTTP Server bind address. Has no effect if web-environment is disabled.
HTTP Server bind port. Has no effect if web-environment is disabled.
Server headers forwarding strategy. Required for Swagger UI when a reverse proxy is used.
Enables or disables HTTP/2 support.
Enables or disables logging of errors with stacktrace when the REST API throws an exception.
Enables or disables SSL support.
Server credentials type. Accepted values: PEM (PEM certificate file), KEYSTORE (Java keystore).
Path to the server certificate file (holds server certificate or certificate chain, may include server private key).
Path to the server certificate private key file. Optional by default. Required if the private key is not present in the server certificate file.
Optional. Server certificate private key password.
Type of the key store. Accepted values: JKS, PKCS12.
Path to the key store that holds the SSL certificate.
Password used to access the key store.
Key alias.
Password used to access the key.
MQTT listeners parameters
Section titled “MQTT listeners parameters”Enables or disables proxy protocol support as a global setting for all listeners. If enabled, supports both v1 and v2. Useful to get the real IP address of the client in the logs, for session details info and unauthorized clients feature.
Netty leak detector level. Accepted values: DISABLED, SIMPLE, ADVANCED, PARANOID. Applied globally for all listeners.
Threshold (in KB) at which Netty considers the channel non-writable. When reached, TBMQ stops delivering data to the subscriber until the channel becomes writable again. Non-persistent clients lose data in this case.
Threshold (in KB) at which Netty considers the channel writable again. When reached, TBMQ resumes delivering data to the subscriber.
Netty socket receive buffer size (in KB). When the buffer limit is reached, TCP triggers backpressure and notifies the sender to slow down. Defaults to 0, which uses the system’s default buffer size.
Enables or disables MQTT TCP port listener.
MQTT TCP listener bind address.
MQTT TCP listener bind port.
Enables or disables proxy protocol support for the MQTT TCP listener. Unset by default — inherits the global MQTT_PROXY_PROTOCOL_ENABLED value. If explicitly set, supports both v1 and v2 and takes precedence over the global setting. Useful to get the real IP address of the client in the logs, for session details info and unauthorized clients feature.
Number of Netty boss group threads.
Number of Netty worker group threads.
Maximum payload size (in bytes).
Enables or disables the TCP keep-alive mechanism to periodically probe the other end of a connection.
Quiet period during graceful shutdown, in which no new tasks are submitted (in s).
Maximum time to wait until the executor is stopped (in s).
Enables or disables MQTT SSL port listener.
MQTT SSL listener bind address.
MQTT SSL listener bind port.
Enables or disables proxy protocol support for the MQTT TLS listener. Unset by default — inherits the global MQTT_PROXY_PROTOCOL_ENABLED value. If explicitly set, supports both v1 and v2 and takes precedence over the global setting. Useful to get the real IP address of the client in the logs, for session details info and unauthorized clients feature.
SSL protocol. See this link for accepted values.
Comma-separated list of cipher suites enabled for the mqtts listener (e.g. TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256). Defaults to empty, meaning all cipher suites supported by the provider are used.
Server credentials type. Accepted values: PEM (PEM certificate file), KEYSTORE (Java keystore).
Path to the server certificate file (holds server certificate or certificate chain, may include server private key).
Path to the server certificate private key file. Optional by default. Required if the private key is not present in the server certificate file.
Optional. Server certificate private key password.
Type of the key store. Accepted values: JKS, PKCS12.
Path to the key store that holds the SSL certificate.
Password used to access the key store.
Optional. Alias of the private key. If not set, the platform will load the first private key from the keystore.
Optional. Password to access the private key. If not set, the platform will attempt to load private keys that are not password-protected.
Number of Netty boss group threads.
Number of Netty worker group threads.
Maximum payload size (in bytes).
Enables or disables the TCP keep-alive mechanism to periodically probe the other end of a connection.
Quiet period during graceful shutdown, in which no new tasks are submitted (in s).
Maximum time to wait until the executor is stopped (in s).
Enables or disables MQTT WS port listener.
MQTT WS listener bind address.
MQTT WS listener bind port.
Enables or disables proxy protocol support for the MQTT WS listener. Unset by default — inherits the global MQTT_PROXY_PROTOCOL_ENABLED value. If explicitly set, supports both v1 and v2 and takes precedence over the global setting. Useful to get the real IP address of the client in the logs, for session details info and unauthorized clients feature.
Enables or disables honoring HTTP forward headers (X-Forwarded-For, X-Real-IP) on the WebSocket upgrade request to derive the real client IP. Useful when TBMQ sits behind an HTTP reverse proxy (e.g. NGINX) that cannot send the PROXY protocol on HTTP location blocks. When enabled, X-Forwarded-For (leftmost IP) wins over X-Real-IP. Falls back to the raw socket address if no usable header is present. Ignored when proxy protocol is enabled for this listener (per-listener or via the global listener.proxy_enabled) — PROXY protocol takes precedence. SECURITY: only enable this when TBMQ is behind a trusted reverse proxy that overwrites these headers; otherwise clients can spoof their source IP.
Comma-separated list of subprotocols that the WebSocket can negotiate. The subprotocol setting mqtt represents MQTT 3.1.1 and MQTT 5.
Number of Netty boss group threads.
Number of Netty worker group threads.
Maximum payload size (in bytes).
Enables or disables the TCP keep-alive mechanism to periodically probe the other end of a connection.
Quiet period during graceful shutdown, in which no new tasks are submitted (in s).
Maximum time to wait until the executor is stopped (in s).
Enables or disables MQTT WSS port listener.
MQTT WSS listener bind address.
MQTT WSS listener bind port.
Enables or disables proxy protocol support for the MQTT WSS listener. Unset by default — inherits the global MQTT_PROXY_PROTOCOL_ENABLED value. If explicitly set, supports both v1 and v2 and takes precedence over the global setting. Useful to get the real IP address of the client in the logs, for session details info and unauthorized clients feature.
Enables or disables honoring HTTP forward headers (X-Forwarded-For, X-Real-IP) on the WebSocket upgrade request to derive the real client IP. Useful when TBMQ sits behind an HTTP reverse proxy (e.g. NGINX) that cannot send the PROXY protocol on HTTP location blocks. When enabled, X-Forwarded-For (leftmost IP) wins over X-Real-IP. Falls back to the raw socket address if no usable header is present. Ignored when proxy protocol is enabled for this listener (per-listener or via the global listener.proxy_enabled) — PROXY protocol takes precedence. SECURITY: only enable this when TBMQ is behind a trusted reverse proxy that overwrites these headers; otherwise clients can spoof their source IP.
SSL protocol. See this link for accepted values.
Comma-separated list of cipher suites enabled for the wss listener (e.g. TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256). Defaults to empty, meaning all cipher suites supported by the provider are used.
Server credentials type. Accepted values: PEM (PEM certificate file), KEYSTORE (Java keystore).
Path to the server certificate file (holds server certificate or certificate chain, may include server private key).
Path to the server certificate private key file. Optional by default. Required if the private key is not present in the server certificate file.
Optional. Server certificate private key password.
Type of the key store. Accepted values: JKS, PKCS12.
Path to the key store that holds the SSL certificate.
Password used to access the key store.
Optional. Alias of the private key. If not set, the platform will load the first private key from the keystore.
Optional. Password to access the private key. If not set, the platform will attempt to load private keys that are not password-protected.
Comma-separated list of subprotocols that the WebSocket can negotiate. The subprotocol setting mqtt represents MQTT 3.1.1 and MQTT 5.
Number of Netty boss group threads.
Number of Netty worker group threads.
Maximum payload size (in bytes).
Enables or disables the TCP keep-alive mechanism to periodically probe the other end of a connection.
Quiet period during graceful shutdown, in which no new tasks are submitted (in s).
Maximum time to wait until the executor is stopped (in s).
Kafka parameters
Section titled “Kafka parameters”Number of parallel consumers for ‘tbmq.msg.all’ topic. Should not be more than the number of partitions in topic.
Number of threads in the pool to process consumers tasks. Should not be less than number of consumers.
Poll interval for messages from ‘tbmq.msg.all’ topic (in ms).
Timeout for processing a pack of messages from ‘tbmq.msg.all’ topic (in ms).
Processing strategy for ‘tbmq.msg.all’ topic. Accepted values: SKIP_ALL, RETRY_ALL.
Number of retries. Use 0 for unlimited. Applies to the RETRY_ALL strategy.
Enables or disables parallel processing of consumed messages (grouped by publishing client ID to preserve order). Helpful when the same client publishes lots of messages in a short amount of time. It is recommended to measure the impact of this parameter before enabling it in production.
Poll interval for messages from Application topics (in ms).
Timeout for processing a pack of messages (in ms).
Processing strategy for Application topics. Accepted values: SKIP_ALL, RETRY_ALL.
Number of retries. Use 0 for unlimited. Applies to the RETRY_ALL strategy.
Enables or disables validation that the application client ID contains only alphanumeric characters (required for Kafka topic creation).
Enables or disables validation that the application shared subscription topic filter contains only alphanumeric characters, ‘+’, or ‘#’ (required for Kafka topic creation).
Number of parallel consumers for ‘tbmq.msg.persisted’ topic. Should not be more than the number of partitions in topic.
Number of threads in the pool to process consumers tasks.
Poll interval for messages from ‘tbmq.msg.persisted’ topic (in ms).
Timeout for processing a pack of messages from ‘tbmq.msg.persisted’ topic (in ms).
Queue processing strategy. Accepted values: SKIP_ALL, RETRY_ALL.
Number of retries. Use 0 for unlimited. Applies to the RETRY_ALL strategy.
Time to wait in the consumer thread before retrying (in s).
Poll interval for messages from ‘tbmq.msg.retained’ topic (in ms).
Wait timeout for system messages to be delivered to ‘tbmq.msg.retained’ topic (in ms).
Poll interval for messages from ‘tbmq.client.session’ topic (in ms).
Wait timeout for system messages to be delivered to ‘tbmq.client.session’ topic (in ms).
Poll interval for messages from ‘tbmq.client.subscriptions’ topic (in ms).
Wait timeout for system messages to be delivered to ‘tbmq.client.subscriptions’ topic (in ms).
Number of parallel consumers for tbmq.client.session.event.request topic.
Maximum number of pending client session events.
Poll interval for messages from ‘tbmq.client.session.event.request’ topic (in ms).
Maximum time to process ‘tbmq.client.session.event.request’ messages after consuming them (in ms).
Number of threads for sending event responses to session event requests.
Poll interval for messages from ‘tbmq.client.session.event.response’ topics (in ms).
Maximum time before client session events expire (in ms).
Cleanup period for stale client session events (in ms).
Poll interval for messages from ‘tbmq.client.disconnect’ topics (in ms).
Number of parallel consumers for tbmq.msg.downlink.persisted topics.
Number of threads in the pool to process consumers tasks.
Poll interval for messages from ‘tbmq.msg.downlink.persisted’ topics (in ms).
Number of parallel consumers for tbmq.msg.downlink.basic topics.
Number of threads in the pool to process consumers tasks.
Poll interval for messages from ‘tbmq.msg.downlink.basic’ topics (in ms).
Poll interval for messages from ‘tbmq.sys.app.removed’ topic (in ms).
Cron expression defining when to consume and process messages.
Timezone for the processing cron-job.
Poll interval for messages from ‘tbmq.sys.historical.data’ topic (in ms).
Poll interval for messages from ‘tbmq.ie.uplink’ topic (in ms).
Timeout for processing a pack of messages from ‘tbmq.ie.uplink’ topic (in ms).
Poll interval for messages from ‘tbmq.ie.uplink.notifications’ topics (in ms).
Poll interval for messages from ‘tbmq.sys.internode.notifications’ topics (in ms).
Poll interval for messages from ‘tbmq.client.blocked’ topic (in ms).
Wait timeout for system messages to be delivered to ‘tbmq.client.blocked’ topic (in ms).
List of Kafka bootstrap servers used to establish connection.
Enables or disables deletion of Kafka topics created for Application MQTT Clients or Application Shared subscriptions. When true, TBMQ may automatically remove topics during cleanup (e.g., when an Application client or shared subscription is deleted). When false, TBMQ skips topic deletion and simply stops using them, preventing accidental data loss in production environments.
Base Kafka properties applied to admins, all producers and consumers, making it the ideal place for shared connection and security settings. Format is key:value;key:value. If a property value contains a semicolon (common in sasl.jaas.config), escape it with a backslash (e.g., …username=“user”;password=“pass”;).
Additional Kafka properties specific only to consumers, merged with the global defaults — TB_KAFKA_DEFAULT_PRODUCER_CONSUMER_CONFIG (overriding them if keys conflict). Follows the standard key:value;key:value format. Ensure any internal semicolons in values are escaped as ;.
List of partition assignment strategy class names or types, ordered by preference, used to distribute partition ownership amongst consumer instances when group management is used.
Timeout for detecting client failures when using Kafka’s group management facility (in ms).
Maximum delay between invocations of poll() when using consumer group management (in ms).
Maximum number of records returned in a single call to poll().
Maximum amount of data per partition the server will return (in bytes).
Maximum amount of data the server should return for a fetch request (in bytes).
Expected time between heartbeats to the consumer coordinator when using Kafka’s group management facilities. Heartbeats ensure the consumer’s session stays active and facilitate rebalancing when consumers join or leave. Must be set lower than TB_KAFKA_DEFAULT_CONSUMER_SESSION_TIMEOUT_MS, but typically no higher than 1/3 of that value. Can be adjusted lower to control the expected time for normal rebalances (in ms). Defaults to 3 s.
Additional Kafka properties specific only to producers, merged with the global defaults — TB_KAFKA_DEFAULT_PRODUCER_CONSUMER_CONFIG (overriding them if keys conflict). Follows the standard key:value;key:value format. Ensure any internal semicolons in values are escaped as ;.
Number of acknowledgments the producer requires the leader to have received before considering a request complete.
Number of retries for records whose send fails with a potentially transient error.
Batch size for grouping records sent to the same partition (in bytes).
Delay for grouping records arriving between request transmissions into a batched request (in ms).
Total memory the producer can use to buffer records waiting to be sent to the server (in bytes).
Compression type for all data generated by the producer. Accepted values: none, gzip, snappy, lz4, zstd.
Additional configs separated by semicolon for the admin Kafka client, merged with the global defaults — TB_KAFKA_DEFAULT_PRODUCER_CONSUMER_CONFIG (overriding them if keys conflict).
Kafka Admin client command timeout (in s). Applies to operations like describeCluster, listTopics, etc.
Kafka topics cache TTL (in ms). Defines how long the list of topics is kept in memory before reloading from Kafka. Defaults to 5 minutes.
Enables or disables printing of consumer group lag between consumer offsets and the latest Kafka topic offsets.
Print interval for Kafka consumer group statistics (in ms).
Time to wait for stats-loading requests to Kafka to finish (in ms).
Additional configs separated by semicolon for the Kafka stats consumer, merged with the consumer defaults — TB_KAFKA_DEFAULT_CONSUMER_CONFIG (overriding them if keys conflict).
Additional configs separated by semicolon for the Kafka admin client used on the home page, merged with the consumer defaults — TB_KAFKA_DEFAULT_CONSUMER_CONFIG (overriding them if keys conflict).
Time to wait for home page requests to Kafka to finish (in ms).
Topic for persisting incoming PUBLISH messages.
Kafka topic properties separated by semicolon for the tbmq.msg.all topic.
Additional Kafka consumer configs separated by semicolon for the tbmq.msg.all topic.
Additional Kafka producer configs separated by semicolon for the tbmq.msg.all topic.
Kafka topic properties separated by semicolon for the tbmq.msg.app topics.
Additional Kafka consumer configs separated by semicolon for the tbmq.msg.app topics.
Additional Kafka producer configs separated by semicolon for the tbmq.msg.app topics.
Kafka topic properties separated by semicolon for application shared subscription topics.
Additional Kafka consumer configs separated by semicolon for application shared subscription topics.
Additional Kafka producer configs separated by semicolon for application shared subscription topics.
Topic for persisting messages related to Device clients before saving them in the database.
Kafka topic properties separated by semicolon for the tbmq.msg.persisted topic.
Additional Kafka consumer configs separated by semicolon for the tbmq.msg.persisted topic.
Additional Kafka producer configs separated by semicolon for the tbmq.msg.persisted topic.
Topic for retained messages.
Kafka topic properties separated by semicolon for the tbmq.msg.retained topic.
Additional Kafka consumer configs separated by semicolon for the tbmq.msg.retained topic.
Additional Kafka producer configs separated by semicolon for the tbmq.msg.retained topic.
Topic for persisting client sessions.
Kafka topic properties separated by semicolon for the tbmq.client.session topic.
Additional Kafka consumer configs separated by semicolon for the tbmq.client.session topic.
Additional Kafka producer configs separated by semicolon for the tbmq.client.session topic.
Topic for persisting client subscriptions.
Kafka topic properties separated by semicolon for the tbmq.client.subscriptions topic.
Additional Kafka consumer configs separated by semicolon for the tbmq.client.subscriptions topic.
Additional Kafka producer configs separated by semicolon for the tbmq.client.subscriptions topic.
Topic for sending client session event requests.
Kafka topic properties separated by semicolon for the tbmq.client.session.event.request topic.
Additional Kafka consumer configs separated by semicolon for the tbmq.client.session.event.request topic.
Additional Kafka producer configs separated by semicolon for the tbmq.client.session.event.request topic.
Prefix for topics used to send client session event responses to Broker nodes.
Kafka topic properties separated by semicolon for the tbmq.client.session.event.response topics.
Additional Kafka consumer configs separated by semicolon for the tbmq.client.session.event.response topics.
Additional Kafka producer configs separated by semicolon for the tbmq.client.session.event.response topics.
Prefix for topics used to send disconnect client commands to Broker nodes.
Kafka topic properties separated by semicolon for the tbmq.client.disconnect topics.
Additional Kafka consumer configs separated by semicolon for the tbmq.client.disconnect topics.
Additional Kafka producer configs separated by semicolon for the tbmq.client.disconnect topics.
Prefix for topics for non-persistent Device messages that should be transferred to other Broker nodes.
Kafka topic properties separated by semicolon for the tbmq.msg.downlink.basic topics.
Additional Kafka consumer configs separated by semicolon for the tbmq.msg.downlink.basic topics.
Additional Kafka producer configs separated by semicolon for the tbmq.msg.downlink.basic topics.
Prefix for topics for persistent Device messages that should be transferred to other Broker nodes.
Kafka topic properties separated by semicolon for the tbmq.msg.downlink.persisted topics.
Additional Kafka consumer configs separated by semicolon for the tbmq.msg.downlink.persisted topics.
Additional Kafka producer configs separated by semicolon for the tbmq.msg.downlink.persisted topics.
Topic for sending events to remove application topics when application clients are changed to device clients.
Kafka topic properties separated by semicolon for the tbmq.sys.app.removed topic.
Additional Kafka consumer configs separated by semicolon for the tbmq.sys.app.removed topic.
Additional Kafka producer configs separated by semicolon for the tbmq.sys.app.removed topic.
Topic for sending historical data stats to be summed from each broker.
Kafka topic properties separated by semicolon for the tbmq.sys.historical.data topic.
Additional Kafka consumer configs separated by semicolon for the tbmq.sys.historical.data topic.
Additional Kafka producer configs separated by semicolon for the tbmq.sys.historical.data topic.
Prefix for topics used to send integration configurations and validation requests from TBMQ to integration executors.
Kafka topic properties separated by semicolon for the tbmq.ie.downlink.http topic.
Additional Kafka consumer configs separated by semicolon for the tbmq.ie.downlink.http topic.
Additional Kafka producer configs separated by semicolon for the tbmq.ie.downlink.http topic.
Kafka topic properties separated by semicolon for the tbmq.ie.downlink.kafka topic.
Additional Kafka consumer configs separated by semicolon for the tbmq.ie.downlink.kafka topic.
Additional Kafka producer configs separated by semicolon for the tbmq.ie.downlink.kafka topic.
Kafka topic properties separated by semicolon for the tbmq.ie.downlink.mqtt topic.
Additional Kafka consumer configs separated by semicolon for the tbmq.ie.downlink.mqtt topic.
Additional Kafka producer configs separated by semicolon for the tbmq.ie.downlink.mqtt topic.
Topic for sending messages and events from integration executors to TBMQ.
Kafka topic properties separated by semicolon for the tbmq.ie.uplink topic.
Additional Kafka consumer configs separated by semicolon for the tbmq.ie.uplink topic. A pack’s events are processed one at a time per integration to keep their order, so max.poll.records bounds how long a single integration’s chain can get within one pack, and with it the pack processing time.
Additional Kafka producer configs separated by semicolon for the tbmq.ie.uplink topic.
Prefix for topics used to send notifications or replies from integration executors to specific TBMQ nodes.
Kafka topic properties separated by semicolon for the tbmq.ie.uplink.notifications topics.
Additional Kafka consumer configs separated by semicolon for the tbmq.ie.uplink.notifications topic.
Additional Kafka producer configs separated by semicolon for the tbmq.ie.uplink.notifications topic.
Kafka topic properties separated by semicolon for the tbmq.msg.ie topics.
Additional Kafka consumer configs separated by semicolon for the tbmq.msg.ie topics.
Additional Kafka producer configs separated by semicolon for the tbmq.msg.ie topics.
Kafka topic properties separated by semicolon for the dedicated tbmq.ie.event lifecycle-event topics. Retention defaults shorter than the data topic since events are best-effort hints.
Additional Kafka consumer configs separated by semicolon for the tbmq.ie.event topics.
Additional Kafka producer configs separated by semicolon for the tbmq.ie.event topics. Lifecycle events are produced synchronously on the MQTT processing thread. Before the first send to a given integration’s event topic, the producer provisions it through the admin client, which can block on queue.kafka.admin.command-timeout (30 s default) twice - once to list existing topics, once to create the missing one - a bound that dwarfs max.block.ms below it. A failed topic listing during a Kafka outage is cached empty for queue.kafka.admin.topics-cache-ttl-ms (300 s default, floored at 60 s), so every event sent in that window still pays a fresh topic-creation attempt. Lower max.block.ms to tighten the smaller, producer-side bound at the cost of more dropped events under Kafka pressure.
Prefix for topics used to send system notifications to Broker nodes.
Kafka topic properties separated by semicolon for the tbmq.sys.internode.notifications topics.
Additional Kafka consumer configs separated by semicolon for the tbmq.sys.internode.notifications topics.
Additional Kafka producer configs separated by semicolon for the tbmq.sys.internode.notifications topics.
Topic for blocked clients.
Kafka topic properties separated by semicolon for the tbmq.client.blocked topic.
Additional Kafka consumer configs separated by semicolon for the tbmq.client.blocked topic.
Additional Kafka producer configs separated by semicolon for the tbmq.client.blocked topic.
Common prefix for all Kafka topics, producers, consumer groups, and consumers. Defaults to empty string, meaning no prefix is applied.
General service parameters
Section titled “General service parameters”Microservice type. Accepted values: tbmq.
Unique ID for this service. Autogenerated if empty.
Actor system parameters
Section titled “Actor system parameters”Number of messages the actor system will process per actor before switching to processing messages for the next actor.
Thread pool size for the actor system scheduler.
Maximum number of attempts to initialize the actor before disabling it.
Time the actor system waits during TBMQ node shutdown to process client disconnections (in ms).
Number of threads processing the Device actor’s messages.
Time to wait before deleting the Device actor after disconnect (in minutes).
Number of threads processing the MQTT client actor messages.
Time to wait before stopping the actor for clients that did not specify a client ID (in s).
Time to wait before stopping the actor for clients that specified a client ID (in s).
Thread pool size for the mail sender executor service.
Thread pool size for the password reset emails executor service.
Platform integrations parameters
Section titled “Platform integrations parameters”Timeout for API connection check requests (in s).
Execution period of the cleanup task for disconnected integrations (in s). Defaults to three hours.
Administration TTL for cleaning up disconnected integrations (in s). The cleanup deletes both of the integration’s topics, clears its subscriptions, and evicts its lifecycle event types cluster-wide - the integration stops producing altogether, not just loses its topics. Defaults to one week. A value of 0 or negative disables this TTL.
Database time series parameters
Section titled “Database time series parameters”Maximum number of DB queries generated by a single API call to fetch time series records.
SQL configuration parameters
Section titled “SQL configuration parameters”Enables or disables sorting of entities before batch update. Should be enabled in cluster mode to avoid deadlocks.
Partitioning size for timestamp key-value storage. Accepted values: DAYS, MONTHS, YEARS, INDEFINITE.
Enables or disables removal of null characters from strValue before insert.
Batch size for persisting time series inserts.
Maximum timeout for time series entries queue polling (in ms).
Number of threads that execute batch insert/update statements for time series data. Must be a prime number (e.g., 3 or 5) for optimal hash distribution.
Batch size for persisting latest time series inserts.
Maximum timeout for latest time series entries queue polling (in ms).
Number of threads that execute batch insert/update statements for latest time series data. Must be a prime number (e.g., 3 or 5) for optimal hash distribution.
Batch size for persisting unauthorized client inserts.
Maximum timeout for unauthorized client insert entries queue polling (in ms).
Number of threads that execute batch insert/update statements for unauthorized client data. Must be a prime number (e.g., 3 or 5) for optimal hash distribution.
Batch size for processing unauthorized client deletes.
Maximum timeout for unauthorized client delete entries queue polling (in ms).
Number of threads that execute batch delete statements for unauthorized client data. Must be a prime number (e.g., 3 or 5) for optimal hash distribution.
Batch size for persisting events updates.
Maximum timeout for events entries queue polling (in ms).
Number of threads that execute batch insert/update statements for events. Must be a prime number (e.g., 3 or 5) for optimal hash distribution.
Number of hours per events partition. Defaults to one week (168 h).
Maximum number of symbols per event. Event content will be truncated if it exceeds this limit.
Enables or disables TTL (Time To Live) for time series records.
Execution period of the TTL task for time series records (in ms). Defaults to one day.
System TTL value for time series records (in s). Defaults to seven days. Use 0 to disable expiration.
Enables or disables TTL (Time To Live) for unauthorized clients.
Execution period of the TTL task for unauthorized clients (in ms). Defaults to one day.
System TTL value for unauthorized clients (in s). Defaults to three days. Use 0 to disable expiration.
Enables or disables TTL (Time To Live) for event records.
Execution interval for the TTL cleanup task for events (in ms). Defaults to 1 hour.
TTL for events (in s). Defaults to 14 days. Cleanup accuracy depends on the sql.events.partition_size parameter.
Redis lettuce configuration parameters
Section titled “Redis lettuce configuration parameters”Enables or disables auto-flush. If disabled, commands are buffered and flushed based on cmd count or time interval.
Number of buffered commands before flush is triggered. Used when auto-flush is disabled.
Maximum time to buffer commands before flushing, regardless of cmd count (in ms).
Maximum time to wait for a Lettuce command to complete (in s). Affects health checks and any command execution (e.g. GET, SET, PING). Reduce this value to fail fast if Redis is unresponsive.
Quiet period for the Lettuce client shutdown (in s).
Shutdown timeout for the Lettuce client (in s).
Enables or disables periodic cluster topology updates. Useful for Redis Cluster setup to handle topology changes, such as node failover, restarts, or IP address changes.
Interval for periodic cluster topology updates (in s).
SQL DAO configuration parameters
Section titled “SQL DAO configuration parameters”Enables or disables the Spring Data JPA repositories support.
Enables or disables OSIV.
Hibernate DDL behavior. Accepted values: none, validate, update, create-drop. Spring Boot chooses a default based on whether it thinks your database is embedded (default create-drop) or not (default none).
Database driver for Spring JPA.
Database connection URL.
Database username.
Database user password.
Maximum number of connections in the pool. Grows with demand to prevent resource exhaustion affecting performance and availability.
Maximum lifetime of a connection (in ms). The connection is removed only when closed. Defaults to 10 minutes.
Maximum time HikariCP will wait to acquire a connection from the pool (in ms). If exceeded, an exception is thrown. Defaults to 30 s.
General Spring parameters
Section titled “General Spring parameters”The server waits for active requests to finish up to the specified time before graceful shutdown.
Enables or disables Hibernate’s own (non-contextual) LOB implementation. When enabled, replaces JDBC contextual LOB creation to fix a Postgres JPA error.
Default ordering for null values.
Enables or disables Spring Data Redis repositories scanning.
Enables or disables the Spring Freemarker check that the template location exists.
Default timeout for asynchronous requests (in ms).
Path matching strategy used for Swagger endpoints.
Security parameters
Section titled “Security parameters”User JWT Token expiration time (in s). Defaults to 2.5 hours.
User JWT Refresh Token expiration time (in s). Defaults to 1 week.
User JWT Token issuer.
User JWT Token sign key.
Enables or disables access to other Administrators’ JWT tokens by the System Administrator.
Enables or disables case-sensitive username login.
Enables or disables persistence of unauthorized client connection attempts. When disabled, unauthorized clients are logged only and are not stored. When enabled, unauthorized client entries are persisted to the database.
MQTT parameters
Section titled “MQTT parameters”Number of threads for the client connection thread pool.
Enables or disables parallel processing of subscriptions for published messages. Helpful when the PUBLISH message should be delivered to lots of subscribers. It is recommended to measure the impact of this parameter before enabling it in production.
Maximum number of messages stored in the queue before the client connects and starts processing them.
Maximum number of PUBLISH messages not yet acknowledged.
Enables or disables the MQTT 5 flow control feature for the server. If disabled, the server will not control the number of messages sent to subscribers via “Receive Maximum”. Also applies to MQTT 3.x clients when enabled. “Receive Maximum” for MQTT 3.x clients can be configured using MQTT_FLOW_CONTROL_MQTT_3X_RECEIVE_MAX.
Interval between sweeps of the per-client delayed-message buffer that drops messages whose age exceeds ‘ttl’ (in ms). Drain on ACK/writability is event-driven, so this sweeper only handles TTL expiry. Defaults to 10 s. The legacy YAML key ‘mqtt.flow-control.timeout’ and env var MQTT_FLOW_CONTROL_TIMEOUT remain honoured as fallbacks for upgrade compatibility.
Time to store delayed messages for subscribers (in s). Delayed messages are those that cannot be sent immediately due to flow control restrictions. Defaults to 10 minutes.
Maximum allowed queue length for delayed messages — published to the client when the in-flight window is full.
Receive maximum value for MQTT 3.x clients.
Interval between subsequent checks for inactive clients (in ms).
Maximum keep-alive value allowed by the server (in s). Applies to MQTT v5 clients. Defaults to 10 minutes.
Maximum number of segments in topics. Excessively large values may cause processing errors. Defaults to 0, which disables the limit.
Maximum number of topic aliases per connection. Defaults to 0, which disables the Topic Alias feature.
Minimum topic name length that the broker may replace with a topic alias (e.g., topics with more than 50 characters).
Enables or disables client subscriptions to the root multi-level wildcard “#”. When true (default), clients can subscribe to “#” and receive a copy of every message published to the broker. Useful for debugging or firehose-style monitoring services. When false, clients are denied subscription to the exact topic “#” but can still subscribe to specific paths (e.g., “sensors/#”) or individual topics. Recommended for production to prevent accidental or malicious data leakage.
Processing strategy for distributing messages among clients in a shared subscription. Accepted values: ROUND_ROBIN.
Maximum pause for clearing subscription storage from empty nodes (in ms). If a wait is unsuccessful, subscribing clients will be resumed, but the clear will fail.
Cron job to schedule clearing of empty subscription nodes. Defaults to ‘every day at midnight’.
Timezone for the subscription clearing cron-job.
Maximum pause for clearing retain msg storage from empty nodes (in ms). If a wait is unsuccessful, retain messages processing will be resumed, but the clear will fail.
Cron job to schedule clearing of empty retain msg nodes. Defaults to ‘every day at midnight’.
Timezone for the retain msg clearing cron-job.
Processing period for clearing retained messages by the MQTT expiry feature (in ms).
Cron job to schedule clearing of expired and inactive client sessions. Defaults to ‘every hour’, e.g. at 20:00:00 UTC.
Timezone for the client sessions clearing cron-job.
Maximum allowed expiry interval for inactive sessions (in s). Defaults to one week.
Administration TTL for clearing sessions that do not expire by session expiry interval (in s). (e.g. MQTTv3 cleanSession=false or MQTTv5 cleanStart=false && sessionExpiryInterval == 0). Defaults to one week. A value of 0 or negative disables this TTL.
Maximum client ID length for MQTT 3.1.
Enables or disables immediate flush of each message published to non-persistent subscribers. When disabled, messages are buffered and flushed periodically.
Number of messages buffered in the channel before the flush is made. Used when MQTT_MSG_WRITE_AND_FLUSH = false.
When either MQTT_MSG_WRITE_AND_FLUSH or MQTT_PERSISTENT_MSG_WRITE_AND_FLUSH is set to false, the broker buffers outgoing messages in the outbound channel to improve throughput. The respective buffer sizes are controlled by MQTT_BUFFERED_MSG_COUNT (for non-persistent clients) and MQTT_PERSISTENT_BUFFERED_MSG_COUNT (for persistent clients). Maximum number of session entries stored in the flush state cache. When the cache exceeds this size, the least recently used sessions are evicted and their pending message buffers are flushed automatically.
Expiry time for an inactive session entry in the flush cache (in ms). A session is considered inactive if it receives no new messages during this period. Upon expiration, the session is evicted from the cache and its buffer is flushed. Defaults to 5 minutes.
Interval at which the scheduler checks all sessions in the cache for potential flushing (in ms). A smaller value results in more frequent flush checks.
Maximum time a session can remain idle before its message buffer is automatically flushed to the client (in ms). A flush occurs either when the buffer limit is reached or when this timeout elapses.
Maximum number of PUBLISH messages stored for each persisted DEVICE client.
TTL of persisted DEVICE messages (in s). Defaults to one week.
Enables or disables immediate flush of each message published to persistent DEVICE client subscribers. When disabled, messages are buffered and flushed periodically.
Number of messages buffered in the channel before the flush is made. Used when MQTT_PERSISTENT_MSG_WRITE_AND_FLUSH = false.
Enables or disables immediate flush of each message published to persistent APPLICATION client subscribers. When disabled, messages are buffered and flushed periodically.
Number of messages buffered in the channel before the flush is made. Used when MQTT_APP_MSG_WRITE_AND_FLUSH = false.
Enables or disables the cluster-wide total throughput quota. The quota counts MQTT PUBLISH packets against one budget shared by the whole cluster, and charges them when the publish is processed — before it is stored. A publish costs 1 packet for the incoming message plus 1 for every subscriber, shared subscription group and integration it is routed to. Once a message has been charged and stored it is delivered without any further charge: a persistent session that reconnects after being offline receives its whole backlog as fast as the cluster can deliver it, however large, and QoS 1/2 retransmissions are free. The one exception is a retained message sent to a client that subscribes later — that is a new outgoing packet which nothing has paid for yet, so it is charged when the subscription is made. On overuse, incoming publishes are refused (MQTT 5: PUBACK/PUBREC with reason code 0x97 QUOTA_EXCEEDED; MQTT 3.x: disconnect) and the copies for subscribers beyond the remaining budget are never stored, which is reported in the droppedMsgs statistic. If Redis becomes unavailable the quota keeps granting for degraded-grace-ms so a failover passes unnoticed, then stops granting rather than serve unmetered traffic indefinitely (see the throughputQuotaDegraded metric and degraded-grace-ms below).
Quota bucket definition. Comma-separated list of capacity:seconds bandwidths. Each bandwidth refills continuously over the given period, so the sustained rate is capacity / seconds and the capacity is the volume of unused budget that accumulates for a burst. The default 50000:60 allows ~833 messages per second sustained, and after 10 idle seconds a burst of 8333 is available at once. The maximum burst is the WHOLE capacity, so after a full idle minute the default admits 50000 messages at once — 60x the sustained rate. The capacity is also the largest amount a SINGLE publish can charge, because a publish pays for its whole fan-out at once — keep it above your widest fan-out. Note that configuring MORE THAN ONE bandwidth lowers that ceiling to the smallest capacity among them (bucket4j requires every bandwidth to hold the tokens for a single charge), so 1000:1,50000:60 would sustain the same ~833 per second but truncate any fan-out above 1000, even on an idle cluster. To allow a smaller burst without capping the fan-out, keep ONE bandwidth and shorten the period at the same ratio rather than adding a second one: 5000:6 sustains the same ~833 messages per second as 50000:60 with a tenth of the burst. Your widest fan-out is the floor on capacity, so a burst ceiling below it cannot be expressed — one publish must always be able to charge for every subscriber it reaches. Applied on broker start. Changing this value carries the spent tokens over proportionally while a single bandwidth is configured; with more than one it resets the token counters across the cluster instead, granting one full interval of fresh budget.
Number of quota tokens a broker node draws from Redis per replenishment round-trip. Defaults to 0, which derives max(1, sustainedRate / 10) from the config above. Larger blocks reduce Redis calls but let idle nodes hold more of the cluster budget between lease-return ticks. A publish whose fan-out exceeds the node’s drawn tokens draws the shortfall on demand, so this value does not cap a single publish.
Period of the background tick that returns a node’s unused drawn tokens to the shared Redis bucket (in ms). Defaults to 1000. Set to 0 to disable the return tick — but note that a node which draws a block and then goes quiet then holds those tokens indefinitely, so the cluster’s effective budget shrinks by the sum of every idle node’s lease. Leave the tick on unless traffic is even across all nodes.
How long the quota keeps granting after it loses the shared Redis bucket (in ms). Defaults to 30000, which covers a Redis Cluster or Sentinel failover, so a node rides out the switch without refusing anything. Past this the node stops granting: it cannot tell how much budget the cluster has left, and continuing would serve unmetered traffic for as long as Redis stays away. The window measures ONE continuous outage — it starts when the first draw fails and is NOT extended by later failures — and any successful draw resets it, so an intermittent Redis never accumulates toward the deadline. Raising it trades enforcement for availability; 0 refuses the moment a draw fails. Note that once the window has elapsed, publishes are refused exactly as they are on a spent budget: reported in droppedMsgs, MQTT 5 clients get 0x97 QUOTA_EXCEEDED and MQTT 3.x clients are disconnected.
Enables or disables publish rate limits per client for incoming messages to the broker.
Limits the count of publish messages per publisher per time interval (in s). Comma-separated list of limit:seconds pairs. Example: 10 messages per second or 300 messages per minute.
Enables or disables publish rate limits per client for outgoing messages to subscribers. Applies only to non-persistent subscribers with QoS = 0 (“AT_MOST_ONCE”).
Limits the count of publish messages per subscriber per time interval (in s). Comma-separated list of limit:seconds pairs. Example: 10 messages per second or 300 messages per minute.
Enables or disables Device clients persisted messages rate limits for the broker (per whole cluster).
Limits the count of Device clients persisted messages per time interval (in s). Comma-separated list of limit:seconds pairs. Example: 100 messages per second or 1000 messages per minute. Applied on broker start. Changing this value resets the token counters across the cluster when more than one limit:seconds pair is configured, granting one full interval of fresh budget.
Total limit of sessions (connected + disconnected) stored on the broker, applied collectively across the cluster, not per node. For example, when set to 1000, the entire cluster can store 1000 sessions in total. This is a soft limit, meaning slightly more sessions may be stored. Defaults to 0, which disables the limit.
Total limit for Application persistent clients and external system integrations. Defaults to 0, which disables the limit.
Number of threads in the pool for processing all publish messages callbacks after sending them to Kafka.
Number of threads in the pool for processing device persisted publish messages callbacks after sending them to Kafka.
Number of threads in the pool for processing application persisted publish messages callbacks after sending them to Kafka.
Number of threads in the pool for processing downlink messages callbacks after sending them to Kafka.
Response info value for the MQTT 5 request-response feature, returned to clients that request it. If not set, the broker will not reply with response info to MQTT 5 clients that connect with “request response info” = 1. Set it to the topic to be used for the request-response feature, e.g. “example/”.
Execution period of the cleanup task for expired blocked clients (in minutes). Defaults to five minutes.
TTL for expired blocked clients (in minutes). After this time, the expired blocked client is removed completely. Defaults to one week.
Connectivity properties
Section titled “Connectivity properties”Path to the MQTT root CA certificate file.
Filename for the downloaded MQTT root CA certificate.
Cache parameters
Section titled “Cache parameters”Enables or disables cache stats logging.
Cache stats logging interval (in s).
Common prefix for all cache keys. Defaults to empty string, meaning no prefix is applied.
Cache TTL (in minutes). Defaults to 1 day.
Cache TTL (in minutes). Recommended to set a small value to limit credential storage duration (e.g., 1-5 minutes).
Cache TTL (in minutes). Defaults to 1 day.
Cache TTL (in minutes). Defaults to 0, meaning the cache is eternal.
Cache TTL (in minutes). Defaults to 0, meaning the cache is eternal.
Redis configuration parameters
Section titled “Redis configuration parameters”Connection type. Accepted values: standalone, cluster, sentinel.
Redis connection host.
Redis connection port.
Enables or disables the default Redis client configuration.
Client name. Applies only when not using the default ClientConfig.
Connection timeout (in ms). Applies only when not using the default ClientConfig.
Read timeout (in ms). Applies only when not using the default ClientConfig.
Enables or disables pool config. Applies only when not using the default ClientConfig.
Comma-separated list of “host:port” pairs to bootstrap from.
Maximum number of redirects to follow when executing commands across the cluster.
Enables or disables use of the default pool config. When false, the pool config is built from the ‘pool_config’ section values.
Name of the master node.
Comma-separated list of “host:port” pairs of sentinels.
Optional. Username to authenticate with the Sentinel (Sentinel ACL).
Password to authenticate with the Sentinel.
Enables or disables use of the default pool config. When false, the pool config is built from the ‘pool_config’ section values.
DB index.
Optional. Username for Redis ACL authentication (Redis 6+).
DB password.
Enables or disables TLS for Redis connections. Applies to all connection types: standalone, sentinel, cluster.
Path to the CA certificate PEM file used to verify the Redis server certificate. Required when SSL is enabled.
Optional. Path to the client certificate PEM file. Required only for mutual TLS (mTLS).
Optional. Path to the client private key PEM file. Required only for mutual TLS (mTLS).
Maximum number of connections that can be allocated by the connection pool.
Maximum number of idle connections that can be maintained in the pool without being closed.
Minimum number of idle connections that can be maintained in the pool without being closed.
Enables or disables the PING command sent when a connection is borrowed.
Enables or disables testing the connection before returning it to the pool.
Enables or disables using the PING command to monitor connection validity during idle resource monitoring. Invalid connections are destroyed.
Minimum time a connection must be idle before it can be evicted from the pool (in ms).
Time interval between two consecutive eviction runs (in ms).
Maximum time a client is willing to wait for a connection from the pool when all connections are exhausted (in ms).
Number of connections to test for eviction during each eviction run.
Enables or disables blocking when a thread requests a connection from an exhausted pool.
Statistics parameters
Section titled “Statistics parameters”Enables or disables stats printing to the logs.
Print interval for statistics (in ms). Defaults to 1 minute.
Metrics percentiles returned by actuator for timer metrics. List of comma-separated double values.
Enables or disables per-Application-client processing stats. When enabled, each Application client gets its own set of counters tagged with ‘clientId’ (deregistered when the client disconnects); the appProcessor.latency timers are aggregated globally (keyed only by packetType, with no per-client tag). On a broker with very many Application clients the per-client counter cardinality can be high, so enable only when per-client stats are needed.
Persistence frequency of system info such as CPU and memory usage (in s).
Historical data statistics parameters
Section titled “Historical data statistics parameters”Enables or disables historical data stats reporting and persistence to the time series.
Collection period for per-broker statistics (in minutes, range 1-60). Used in the cron expression.
Timezone for the historical data stats processing.
Metrics management parameters
Section titled “Metrics management parameters”Enables or disables disk space health check.
Visibility of full component details in the health endpoint response (e.g., Redis, DB, TBMQ). Accepted values: never - always hide details (default if security is enabled). when-authorized - show details only to authenticated users. always - always include full health details in the response.
Actuator endpoints exposed via HTTP. Use ‘health,info’ to expose only basic health and information endpoints. To expose Prometheus metrics, include ‘prometheus’ in the list (e.g., ‘health,info,prometheus’).
Spring CORS configuration
Section titled “Spring CORS configuration”Comma-separated list of origins to allow. ‘*’ allows all origins. When not set, CORS support is disabled.
Comma-separated list of methods to allow. ‘*’ allows all methods.
Comma-separated list of headers to allow in a request. ‘*’ allows all headers.
How long the response from a pre-flight request can be cached by clients (in s).
Enables or disables credentials support. Defaults to not supported when not set.
Spring doc common parameters
Section titled “Spring doc common parameters”Enables or disables Swagger API docs.
Swagger default produces media-type.
Swagger common parameters
Section titled “Swagger common parameters”General Swagger match pattern for Swagger UI links.
General Swagger security match pattern path for Swagger UI links.
Non-security API path match pattern for Swagger UI links.
Title on the API doc UI page.
Description on the API doc UI page.
Contact name on the API doc UI page.
Contact URL on the API doc UI page.
Contact email on the API doc UI page.
License title on the API doc UI page.
Link to the license body on the API doc UI page.
Version of the API doc to display. Defaults to the package version.
Group name (definition) on the API doc UI page.
Analysis parameters
Section titled “Analysis parameters”Enables or disables analysis logging.
Enables or disables logging events for all clients. When true, ignores the ‘analyzed-client-ids’ list.
Comma-separated list of client IDs for which additional events will be logged. Example env var: ANALYSIS_LOG_CLIENT_IDS=client1,client2.
Was this helpful?