Message History & Replay
BunkerM silently records every MQTT message published through your broker into a local SQLite database. No configuration needed — history starts accumulating from the moment the container starts. Navigate to Logs → Message History to search, filter, and replay any past message.
How It Works
A dedicated background service subscribes to the wildcard topic # and inserts every incoming message into a SQLite database stored at /var/lib/history/history.db inside the container. Internal $SYS/ diagnostic topics are excluded. The service starts automatically with the container — there is nothing to enable.
Text payloads are stored as-is. Binary payloads are automatically base64-encoded and flagged so the UI can display them correctly.
What Gets Stored
Each message record contains:
| Field | Description |
|---|---|
| Timestamp | Millisecond-precision UTC time of receipt |
| Topic | Full MQTT topic path |
| Payload | Message content (binary payloads stored as base64) |
| QoS | Quality of service level (0, 1, or 2) |
| Retain | Whether the message was published with the retain flag |
| Size | Payload size in bytes |
Searching and Filtering
The Message History page provides three ways to narrow the view:
- Topic dropdown — lists every topic seen by the broker with its total message count. Select one to show only messages from that topic.
- Free-text search — matches against both topic path and payload content simultaneously.
- Pagination — 100 messages per page, newest-first. Previous / Next buttons appear when the result set exceeds one page.
The stats bar at the top shows total stored messages, number of unique topics, database size on disk, and the current retention window.
Replaying a Message
Every row in the history table has a Replay button (↺ icon). Clicking it opens a dialog pre-populated with the original topic and payload. Before publishing you can:
- Edit the payload freely
- Change the QoS level (0 / 1 / 2)
- Toggle the retain flag
Clicking Publish sends the message directly to the broker. The replayed message will itself be recorded in history as a new entry.
Retention Limits
BunkerM keeps up to 50,000 messages and 7 days of history by default. When either limit is exceeded, the oldest entries are pruned automatically. You can adjust both limits using environment variables:
docker run -d \
-p 1900:1900 -p 2000:2000 \
-e HISTORY_MAX_MESSAGES=100000 \
-e HISTORY_MAX_AGE_DAYS=14 \
bunkeriot/bunkerm:latestPersisting History Across Restarts
By default, the SQLite database lives inside the container and is lost when the container is removed. Mount a named volume to keep history across restarts:
docker run -d \
-p 1900:1900 -p 2000:2000 \
-v history_data:/var/lib/history \
bunkeriot/bunkerm:latestThe official docker-compose.yml already includes this volume definition — no extra steps needed if you use Compose.
Clearing History
The Clear History button in the top-right corner of the page deletes all stored messages after a confirmation prompt. This operation is irreversible.
Common Use Cases
- Debugging a device — a sensor sent a malformed payload two hours ago. Pull up the history, filter by topic, find the exact message, and inspect the raw content without needing to reproduce the event.
- Regression testing — capture a sequence of real production messages, then replay them against updated firmware or a new subscriber to verify behavior.
- Incident investigation — something tripped an anomaly alert at 3 AM. Go to Message History, filter the relevant topic, and scroll back to the exact timestamp to see what was published.
- Onboarding a new integration — a new service needs to consume your existing MQTT topics. Replay a batch of real messages so it can be tested without waiting for live events.