License

Your TBMQ PE license is more than an entitlement document — the broker reads it at runtime and enforces it. Two of its limits are applied by the broker itself, the cluster-wide throughput quota and the session limit. One is applied by the ThingsBoard License Server when a node starts. The rest either gate a feature or are informational.

This page covers what the license grants, how each grant is enforced, and where to see what you are currently using.

The support tier is derived from the plan rather than purchased on its own: perpetual licenses and plans carrying the priority add-on get Priority help desk, larger subscriptions get Help desk, and the smallest get Community.

1. Open the TBMQ web interface.
2. In the top toolbar, immediately to the left of your user avatar, click the credit card icon.
3. The License info popover opens.

Its header is License info, with a Plans & Pricing link to the right. Below that it lists:

• your plan name — TBMQ PE subscription for a pay-as-you-go plan, TBMQ PE license for a perpetual one — which is itself a link to the pricing page;
• Maximum N messages per second — your licensed throughput;
• N / M sessions — how many sessions are stored right now, against the licensed maximum;
• Maximum N Production instances, and the same for Development instances — crossed out if your plan includes none;
• Unlimited subscriptions and Unlimited integrations;
• your support tier;
• White labeling, ticked when your plan includes it.

The sessions line switches to a warning once you pass 85% of your licensed maximum, which makes the popover a useful early signal; the throughput line does so only once the quota has actually refused traffic. The red badge on the toolbar icon is stricter than either — it counts only the limits you have genuinely reached. Both refresh every minute.

GET /api/admin/licenseUsageInfo returns the same information and requires the system administrator role. An example response:

{
  "maxMessages": 10000,
  "maxSessions": 100000,
  "maxProdInstances": 3,
  "maxDevInstances": 1,
  "whiteLabelingEnabled": true,
  "plan": "TBMQ PE subscription",
  "support": "Help desk",
  "sessionsCount": 42371,
  "totalMsgsLimitReached": false
}

Everything except the last two fields describes the license itself, plan reading TBMQ PE subscription or TBMQ PE license as above. sessionsCount is the live cluster-wide session count, and totalMsgsLimitReached reports whether the throughput quota has refused traffic recently — it is the field to scrape if you want to alert on hitting the licensed ceiling. It stays false while Redis is unreachable, even though the quota may be refusing: see the note under Throughput.

The licensed messages-per-second figure is the quota. TBMQ builds a token bucket of exactly that capacity in Redis and every broker node draws from it, so the budget is shared across the cluster rather than applied per node. It is always enforced: there is no setting that disables it and none that raises it above what the license allows.

A publish is charged when it is admitted, and it pays for its whole fan-out at once. The full charging model — including why replaying a persistent session’s backlog is free and how retained messages are treated — is described in Backpressure, along with the two settings that remain tunable (block-size and lease-return-ms, which only affect how a node draws from the shared budget).

• The publisher is refused. MQTT 5.0 clients receive a PUBACK (QoS 1) or PUBREC (QoS 2) carrying reason code 0x97 Quota exceeded and stay connected; MQTT 3.x clients are disconnected, since the protocol has no way to signal a rejected publish.
• Refusals are counted in the droppedMsgs statistic and listed on the Dropped messages page under reason Rate limits, with details Total rate limits detected. Per-client rate limits carry the same reason, so it is that details string that tells the two apart.
• The broker logs a warning, at most once a minute, naming the metrics to look at.
• A Total messages rate exceeded notification appears at the top of the License info popover. Clearing it is a deliberate act: click the check button (or call DELETE /api/admin/license/ack/totalMessages), which requires the Administrator role. Left alone, it disappears five minutes after it was first raised. It is raised only when the budget is genuinely spent — refusals caused by an unreachable Redis do not raise it.

The session limit counts every session the cluster stores: clients connected right now, plus persistent sessions whose clients are offline but whose state is still kept. A session stops counting once it expires or is removed.

The limit is checked on CONNECT, and only for a client that has no session yet. Reconnecting to an existing session is never refused, and neither is a client taking over its own session, so a client that is already known to the broker can always get back in.

When a new session would push the cluster past the limit, the connection is refused:

Unlike the throughput quota, there is no notification to acknowledge here — the sessions line in the License info popover turns red and the toolbar badge increments for as long as you are at the limit.

An instance is a single TBMQ node registered against your license. A node activates on first start and is refused if your plan’s instance capacity is already taken.

A subscription carries two license keys, a production one and a development one, and the key you set in TBMQ_LICENSE_SECRET decides which pool the node counts against. Activating with the production key also binds the subscription to that cluster, so the same production key cannot bring up a second, separate cluster.

Each node re-checks with the ThingsBoard License Server about once an hour, so a plan change takes effect within the hour — no restart is needed. The shared throughput bucket is reconfigured in place, handing over exactly the tokens an upgrade added or reclaiming exactly those a downgrade removed rather than rescaling what is left, and the session limit is re-read on every check.

If the License Server cannot be reached, the node keeps running on the plan it last retrieved for up to three days. Past that the failure is treated as critical and the node stops.

That cached plan, together with the node’s identity, lives in the file named by TBMQ_LICENSE_INSTANCE_DATA_FILE (tbmq-instance-license.data by default). The broker refuses to start if it cannot write to it, and if the file is lost the node activates again as a new instance — consuming another slot from your instance capacity. Keep it on a volume that survives restarts.

License problems are fatal by design: rather than run in a degraded state, the node logs the error and exits.