You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
FreeDMR/docs/reporting-relay.md

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.

Powered by TurnKey Linux.