---
title: Litmus Unify 2.0.7
slug: unify/ccnh-litmus-unify-202
createdAt: 2026-10-23T19:09:18.609Z
---

## Release type: Security and stability update

Litmus Unify 2.0.7 includes important security updates, dependency improvements, and reliability fixes. We recommend upgrading to this version to maintain the security and stability of your deployment.

Release Date: October 28, 2026

## Security updates

- Updated security-related components and dependencies to address recently disclosed vulnerabilities.
- Improved certificate trust handling through updates to relevant security libraries and components.
- Applied additional security maintenance updates to strengthen the overall security posture of Litmus Unify.

:::hint{type="warning"}
**We strongly recommend that you upgrade to Litmus Unify 2.0.7 or a subsequent security-maintained release.**
:::

## Enhancements

This release makes message delivery and clustering more reliable, adds Kubernetes health probes, and improves upgrades from 2.0.2.

**MQTT:**

- **More reliable clustering.** When a client reconnects to a different node, its session, subscriptions, and queued messages follow it. Each session now has one recorded owner node. Reconnect performance after a restart is also improved.
- **New settings:**
  - `CLIENT_WRITE_TIMEOUT` (default `30s`)
  - `MAXIMUM_INFLIGHT` (default `8192`)
  - `SUBSCRIPTION_STORE_TTL` (default `24h`)
  - `SUBSCRIPTION_STORE_REFRESH_INTERVAL` (default `15 min`)
  - `NATS_SUBS_BUCKET` (default `mqtt_subs`)

:::Paragraph{indent="2"}
Obsolete cleanup settings are still accepted but have no effect.
:::

**Monitoring and logging:**

- **New broker metrics.** New Prometheus counters track the following events. All metric names start with `mqtt_`.
  - Connection refusals
  - Consumer creates, deletes, and rebinds
  - Subscribe failures
  - NATS disconnects and slow consumers
  - Retained-message reads and failures
  - Session moves

**Deployment:**

- **Health endpoints.** These are served on the health-check port (`8082` by default):
  - `/livez` is the liveness probe. It checks that the broker process responds.
  - `/readyz` is the readiness probe. It checks PostgreSQL, the NATS connection, and the Keycloak signing keys.
  - The Helm chart uses both endpoints for its Kubernetes probes.
  - The old `/healthcheck` endpoint remains functional but is deprecated.
- **Ordered startup.** On Kubernetes, the broker waits for PostgreSQL and for every NATS node to be healthy for 45 seconds. The Litmus Unified Namespace Service (LUNS) waits for NATS. On Docker Compose, most services wait for their dependencies to report healthy, and the broker also waits for Keycloak.
- **Configurable stream replicas.** You can set the NATS replica count for the MQTT stream and its key-value buckets with `natsStreamReplicas`.
- **Kubernetes disruption budget.** When more than one broker runs, a PodDisruptionBudget keeps all but one broker available during voluntary evictions, such as node drains.
- **Production single-server installation (preview).** A new Docker Compose package for a single production server includes pre-flight checks, backup, restore, a guided upgrade, and offline installation.

## Resolved issues

**MQTT:**

- **NATS cluster resilience**
  - Publishers and subscribers stay connected through NATS node failures and leader changes.
  - Broker cluster state is now replicated across NATS nodes.
  - The broker no longer depends on a single leader node.
- Fixed an issue where a subscriber could stop receiving messages while its connection looked healthy. The broker now removes consumers that no session uses, and restarts delivery when a pull request to NATS gets no answer.
- Fixed an issue where a session taken over by another broker node could stop receiving messages.
- Fixed an issue where subscribers using the MQTT v5 `No Local` option, such as bridges, could stop receiving messages.
- Fixed an issue where QoS 1 and QoS 2 publishers could stall when a message couldn't be stored. The broker now retries the store. If the retries fail, the broker disconnects the client so that the client resends after reconnecting.
- Fixed an issue where QoS 2 messages could be lost. QoS 2 publishes also always failed for client IDs containing spaces, `@`, or non-ASCII characters.
- Fixed an issue where messages larger than about 786 KB closed the client connection without a reason. The limit is now the 1 MiB NATS limit, minus the topic and message headers. MQTT 5 clients receive reason code `0x95` (Packet Too Large), and MQTT 3.1.1 clients are disconnected.
- Fixed an issue where shared subscriptions were refused unless an ACL rule matched the full `$share/...` filter. ACL rules now check the topic inside the shared subscription (`$share/<group>/<topic>`).
- Fixed an issue where shared subscriptions on different topics in the same group could interfere with each other.
- Fixed an issue where subscriptions could fail to come back after a reconnect.
- Fixed an issue where the broker accepted a connection even when it could not restore the client's saved subscriptions, so the client received nothing. The broker now refuses the connection and keeps the client's queued messages. MQTT 5 clients receive `Server Busy`, and MQTT 3.1.1 clients receive `Server Unavailable`.
- Fixed an issue where retained messages were deleted after 24 hours.
- Fixed an issue where every subscription opened a retained-message watch and logged `failed to watch retained messages` when the watch failed, even when no retained messages were in use. Subscriptions to an exact topic now use a single lookup. Wildcard subscriptions still use a watch.
- Fixed an issue where the broker could stall on clients that stopped reading.
- Fixed an issue where a subscription could be silently dropped when the NATS cluster returned an error.
- Fixed an issue where a JetStream consumer could lose a replica and not recover it. NATS is upgraded from 2.12.5 to 2.12.15.
- Fixed an issue where client connections could time out with `context deadline exceeded` during a reconnect storm. Connecting and subscribing no longer list all consumers on the NATS stream.
- Fixed an issue where a reconnect storm put heavy load on NATS. Session cleanup now runs with a concurrency limit. Each client has its own acknowledgment pool, so one slow client no longer delays others.
- Fixed an issue where each client reserved about 640 KB of send-queue memory for the life of its session. Send queues now grow only as needed, and the broker frees each connection's buffers on disconnect.
- Fixed an issue where a busy connection could be disconnected as a NATS slow consumer because all QoS 0 traffic on a broker shared one NATS connection. QoS 0 traffic now uses a pool of NATS connections.

**Monitoring and logging:**

- Fixed an issue where repeated errors could flood the logs. QoS 0 publish errors, delivery errors, and NATS errors are now logged at most once every five seconds, with a count of the suppressed entries.

**Deployment:**

- Fixed an issue where LUNS could start before NATS was ready on Kubernetes, and then restart.
- Fixed an issue where an upgrade of a loaded cluster could fail to finish. Brokers now wait for NATS before they start, and migrate consumers 16 at a time.
- The broker no longer starts when its database is unreachable.

## Behavior changes

**MQTT:**

- Topics with empty levels are rejected. For example: `/a`, `a/`, and `a//b`.
- Persistent sessions expire after 24 hours offline. Session expiry is capped at 24 hours (86,400 seconds). `SUBSCRIPTION_STORE_TTL` sets the limit.
- Slow subscribers are disconnected. A subscriber whose receive window stays full for five minutes with nothing acknowledged is disconnected. MQTT 5 clients receive reason code `0x93`. A persistent session keeps its queued messages for the reconnect.
- Failed QoS 0 publishes no longer disconnect the client. The broker drops the message and logs the error. This includes oversized QoS 0 messages.
- Shared subscriptions follow topic ACLs. A `$share/...` subscription that a broad rule allowed before may now be denied, and the reverse is also possible. Review the ACLs of any account that uses shared subscriptions.
- Clients may be refused while brokers restore sessions. Most client libraries retry if auto-reconnect is on. Check the reconnect settings of your clients.

## Known issues

**Explore UNS:**

- After a fresh installation, the broker can serve an outdated UNS hierarchy until it restarts. As a workaround, restart the broker once after you install Litmus Unify:
  - Single-node Docker Compose: Run `docker restart tahoe_mqtt`.
  - Cluster Docker Compose: Restart `tahoe_mqtt_1`, `tahoe_mqtt_2`, and `tahoe_mqtt_3`.

**MQTT:**

- A payload of a full 1 MiB is rejected, because the topic and headers count against the 1 MiB NATS limit.
- Retained messages are still limited to about 786 KB. If storing a retained message fails, an MQTT 3.1.1 client still receives a normal PUBACK, so a large retained message can be lost without an error. Keep retained messages small.

**Deployment:**

- The NATS image is not patched for the eMudhra CA compromise. The upstream NATS 2.12.15 image still trusts the emSign ECC Root CA - G3 root. Its server is built with Go 1.25.12, so scanners flag CVE-2026-111943. The risk is low, because NATS does not use TLS in Litmus Unify and makes no connections to public servers.
- Scanners may still report OpenJDK CVE-2026-91403 for Keycloak, because the compromised intermediate CAs are not in the Keycloak blocked list. The risk is low, because the emSign root is removed from the Keycloak trust store.
- Scanners flag the PostgreSQL `gosu` helper, because it is built with Go 1.24.6. The risk is low, because `gosu` only switches the user when the container starts.

## Upgrade

- Litmus Unify was previously called Litmus UNS v2. These release notes cover all changes since 2.0.2.
- To upgrade from 2.0.2 to 2.0.7, follow [Litmus Unify Upgrade Procedure: 2.0.2 to 2.0.7](<../../QuickStart Guides/Litmus Unify Upgrade Procedure 2.0.2 to 2.0.7.mdx>). The upgrade migrates the NATS data, and MQTT clients are offline while it runs, so schedule a maintenance window.
- Downgrading to 2.0.2 isn't supported. Back up before you upgrade.
