7.5 KiB
Reporting Relay
report_sql.py can be the sole client of the FreeDMR TCP reporting socket and
provide a compatible downstream socket for the live dashboard. This avoids
placing multiple reporting consumers on the live server while retaining the
existing netstring protocol.
The existing six positional arguments are unchanged. Enable the relay with:
python report_sql.py freedmr 4321 dbhost dbuser dbpassword logs \
--relay-interface 127.0.0.1 --relay-port 4322
Configure FDMR Monitor to connect to relay port 4322. Use an explicit
container-facing interface instead of 127.0.0.1 when the dashboard runs in a
different container, and restrict access to that interface at the network
boundary. Report configuration and bridge-state messages contain trusted
Python pickle data and must not be exposed to untrusted clients.
The relay forwards upstream messages unchanged and caches only the latest configuration and bridge-state messages so a newly connected dashboard can be initialized immediately. SQL storage accepts both legacy events and extended events with trailing origin fields:
START: type,event,trx,system,streamid,peerid,subid,slot,dstid,source_server,source_rptr
END: type,event,trx,system,streamid,peerid,subid,slot,dstid,duration,source_server,source_rptr
Legacy events remain valid and are stored with null origin columns. The relay
is optional; omitting --relay-port preserves the previous importer behavior.
Optional in-container exporter
The standard FreeDMR container can run one SQL exporter under Supervisor in
both single-worker and HDStack modes. It is disabled by default. Add these
individual values to the existing freedmr service's environment list:
environment:
- REPORT_SQL_ENABLED=1
- REPORT_SQL_DB_HOST=database.example.net
- REPORT_SQL_DB_PORT=3306
- REPORT_SQL_DB_USER=freedmr
- REPORT_SQL_DB_PASSWORD=replace-me
- REPORT_SQL_DB_NAME=logs
No JSON configuration is used. The exporter defaults to the local report feed
at 127.0.0.1:4321, which is the combined worker MUX in HDStack mode. Override
REPORT_SQL_HOST and REPORT_SQL_PORT if needed. Enable reporting in
freedmr.cfg and ensure REPORT_CLIENTS permits 127.0.0.1 when using the
local feed. The exporter does not change reporting settings or their ACLs.
REPORT_SQL_DB_HOST, REPORT_SQL_DB_USER, REPORT_SQL_DB_PASSWORD and
REPORT_SQL_DB_NAME must be supplied. The DB port defaults to 3306. The
password is passed through the process environment, not interpolated into a
shell command or written into generated Supervisor configuration. Protect
the Compose file and Docker access: container environments remain visible to
administrators. Follow Compose's dollar-sign escaping rules for literal $
characters in passwords.
The optional dashboard relay remains disabled (REPORT_SQL_RELAY_PORT=0). To
use it from the existing dashboard container on the private Compose network,
add:
- REPORT_SQL_RELAY_PORT=4330
- REPORT_SQL_RELAY_INTERFACE=0.0.0.0
Then configure the dashboard to use freedmr:4330. Without that interface
override the relay binds only to 127.0.0.1. Choose a free relay port; HDStack
uses the main report port plus the following worker ports, so do not use those
for the relay. No host port is published automatically and no dashboard
configuration is changed. Keep the relay on a trusted network.
Apply the schema update below before enabling the new exporter, and stop any
existing external exporter for this same feed to avoid duplicate writes.
Supervisor manages the exporter separately from the voice processes and sends
its output to the container log. Invalid DB settings or an unavailable database
at startup can exhaust Supervisor's startup retries; correct the cause and
restart the process/container. Reporting remains best effort, without a durable
backlog. Standalone BRIDGE_SERVER=1 mode bypasses Supervisor and does not start
this optional process.
The original six-positional-argument CLI is still supported, with optional
--db-port. For environment-only operation outside the container, run
python report_sql.py --from-env; do not mix this mode with connection arguments.
REPORT_SQL_ENABLED controls container startup only, not an explicitly invoked
exporter.
Talker Alias observations
RX GROUP VOICE,END events can append a JSON object after the two origin
fields, for example:
GROUP VOICE,END,RX,SYSTEM,1234,1001,2342690,2,91,4.25,2341,1001,{"talker_alias":"G7RZU, Simon"}
The existing fields and opcode are unchanged. Events without a completed alias retain their previous wire format. If an alias is available but origin is unavailable, both origin fields are empty. A consumer reading this optional metadata must split END events at most 12 times, then parse the remaining JSON as a whole, not split commas inside the alias. The report payload is UTF-8; JSON escapes quotes, backslashes and control characters. The MUX and relay preserve the tail. Existing positional consumers can ignore it; displaying the alias requires a consumer update and appropriate HTML escaping.
Aliases are observed from embedded LC on received HBP and OpenBridge/FBP group voice calls and reported at normal or timeout completion. Only a complete, validly decoded alias is reported, using its declared character count. Missing blocks and invalid character sequences are not converted into identity evidence. The last complete alias in the over is retained if a later repeat is incomplete. No alias is inherited from an earlier over. DMRA ingestion and live mid-over alias updates are not part of this extension.
This is an unverified, self-declared identity observation, not a replacement for the subscriber callsign lookup. Repeated mesh copies are not independent identity evidence; reconciliation and confidence scoring belong downstream.
SQL deployment order
Add the column before deploying the updated report_sql.py. The exporter
always includes it in the parameterized INSERT, using NULL when no alias is
available, and connects using utf8mb4. Run this once on the feed database:
ALTER TABLE feed
ADD COLUMN talker_alias TEXT CHARACTER SET utf8mb4 NULL;
The older exporter continues to work with the added nullable column, so the schema can be prepared first. FreeDMR itself has no dependency on this schema change; the updated SQL exporter does. There is no automatic migration or fallback to the old INSERT. Global-LH queries and alias presentation remain separate work.
Multiple FreeDMR backends
report_mux.py combines reporting from multiple FreeDMR backend processes
into one compatible reporting socket. It is used by the HDStack container
profile and can also be run directly:
python report_mux.py --listen-interface 127.0.0.1 --listen-port 4321 \
--client 127.0.0.1 \
--backend 1,127.0.0.1,4322 --backend 2,127.0.0.1,4323
Backend numbers are explicit and must be unique. Configuration keys, bridge
member system fields and bridge-event system fields are prefixed with that
number, for example 1:SYSTEM-001. Other fields are preserved. The MUX
reconnects to each backend independently and a reporting-source failure does
not affect the radio proxy. Its backend connections remain open between
updates and accept bounded reporting frames up to 10 MiB so populated worker
snapshots do not trigger Twisted's smaller default netstring limit. A lost
backend connection is reported with its backend number and is re-established
independently. See hdstack.md for the generated container
topology and configuration.