funknetz/docs/svxlink.md

# SvxLink lab for Funknetz

Funknetz must be proven against a local SvxReflector before it touches the live network. This document is that lab: how to run the reflector, what it will accept from a station, and what the wire protocol actually does—so a headset client can be tested without FM-Funknetz credentials.

Upstream SvxLink is two processes with different jobs. `svxlink` is a node: logics, optional radio hardware, modules. `svxreflector` is the conference: stations connect over IP, and it forwards audio among those on the same talk group—one talker at a time. Funknetz is a station on that conference; the lab runs only `svxreflector`. You do not need a full RF node, LocalRx/LocalTx, or EchoLink to exercise the headset client.

## Running a local reflector

Lab compose lives in [`svxlink-docker/`](../svxlink-docker/). It builds upstream SvxLink (community Docker pattern from [f4hlv/svxlink-docker](https://github.com/f4hlv/svxlink-docker)), mounts a minimal `svxreflector.conf`, publishes TCP **and** UDP on the listen port, and runs only `svxreflector`. There is no first-party `sm0svx` image on Docker Hub.

```sh
cd svxlink-docker
docker compose up -d --build
```

| Item | Lab value |
| --- | --- |
| Listen port | **5300** TCP **and** UDP (upstream default; FM-Funknetz production uses 5308) |
| Config | `svxlink-docker/config/svxreflector.conf` → `/etc/svxlink/svxreflector.conf` |
| Auth (protocol 2.0) | `[USERS]` → `[PASSWORDS]`; station `authKey` matches that secret |
| Server cert | `[SERVER_CERT] COMMON_NAME=…` required on first start (current upstream bootstraps a local PKI even for AUTH_KEY clients) |
| Protocol 3 PKI | Material under `/var/lib/svxlink/pki` (compose volume `data/`) |
| Codec | Default **OPUS** when compiled in (`CODECS` optional) |
| Go smoke test | `GOWORK=off go test ./station/ -run TestConnectsToLabReflector -v` (needs libopus; skips if port 5300 is down) |

Point `~/.funknetz.json` at the lab (values match `.env` / the mounted conf; secrets are local-test placeholders):

```json
{
  "host": "127.0.0.1",
  "port": 5300,
  "callsign": "DL0FN-1",
  "authKey": "local-lab-secret-change-me",
  "talkGroup": 9,
  "enableLogging": false,
  "logFile": "/tmp/funknetz.log"
}
```

A second station can use callsign `DL0FN-2` with the same auth key. Do not reuse production FM-Funknetz credentials in the lab.

## What the reflector admits

The binary does not know “Funknetz” or “HamLink.” It admits a station by protocol version, callsign shape, proof of the auth key (or a certificate on protocol 3), and uniqueness of that callsign on the session. App names are never checked. FM-Funknetz’s tickets, issued keys, and the published rule to use ReflectorV2 are **network policy** layered on top of the same knobs—not a separate allowlist inside `svxreflector`.

| Check | Behavior |
| --- | --- |
| Protocol version | Client announces major/minor. Server accepts about **0.6** through **3.0**. Major ≥ 3 takes the certificate/TLS path; older clients get an HMAC challenge. |
| Callsign | Must match `ACCEPT_CALLSIGN` (default: typical ham callsign, optional `-suffix`); optional `REJECT_CALLSIGN` blocks. |
| Auth key (protocol < 3) | Callsign must map in `[USERS]` to a `[PASSWORDS]` secret. Client proves it with HMAC-SHA1 over a 20-byte challenge. Wrong or missing → “Access denied.” |
| Certificates (protocol ≥ 3) | Mutual TLS; peer cert CN is the callsign and must pass the same callsign checks. |
| Unique session | A second concurrent login with the same callsign is denied. |
| Talk group | Optional per-TG `ALLOW` / `ALLOW_MONITOR` regexes after login. |
| Software / version string | **None.** Optional node-info JSON is for status only. |

For the lab and for production as FM-Funknetz documents it, the station speaks **protocol 2.0** (ReflectorV2): auth key, not certificates. Upstream’s man page treats AUTH_KEY as deprecated for “modern” reflectors; that is a different target than the live network’s written instruction.

## Wire protocol

There is no separate RFC. The contract is the message types in upstream SvxLink (`ReflectorMsg.h` and the client logics). Control rides **TCP** as length-prefixed frames (4-byte big-endian length, then payload). Audio and UDP keepalives ride **UDP** to the same host and port. Message types are numeric. Protocol **2.0** authenticates with the auth-key HMAC and sends plaintext UDP with a header of type, client id, and sequence. Protocol **3.0** uses X.509/TLS and encrypts UDP (AES-128-GCM). Funknetz targets 2.0.

Typical protocol 2.0 login:

1. TCP connect to the listen port.
2. Station → `MsgProtoVer` major **2**, minor **0**.
3. Reflector → `MsgAuthChallenge` (20 random bytes).
4. Station → `MsgAuthResponse` (callsign + HMAC-SHA1 digest over the challenge; the auth key is never sent as its own field).
5. Reflector → `MsgAuthOk`, then `MsgServerInfo` (client id, codec list, connected nodes).
6. Station opens UDP to the same host/port; sends heartbeats; selects or monitors talk groups; sends audio as `MsgUdpAudio`.

User messages (type ≥ 100) matter only after the session is connected. Unknown types are ignored for forward compatibility. One talker per talk group; other stations’ audio on that group is ignored until the talker stops.

### TCP messages

| Type | Name | Role |
| --- | --- | --- |
| 1 | `MsgHeartbeat` | Keep the TCP session alive |
| 5 | `MsgProtoVer` | Station announces major/minor (first message) |
| 6 | `MsgProtoVerDowngrade` | Reflector asks for a lower version |
| 10 | `MsgAuthChallenge` | Starts auth-key auth |
| 11 | `MsgAuthResponse` | Callsign + HMAC digest |
| 12 | `MsgAuthOk` | Auth succeeded |
| 13 | `MsgError` | Fatal; peer should disconnect |
| 14–21 | Encryption / CSR / CA | Protocol 3 certificate setup |
| 100 | `MsgServerInfo` | Client id, nodes, codecs |
| 102 / 103 | `MsgNodeJoined` / `MsgNodeLeft` | Presence |
| 104 / 105 | `MsgTalkerStart` / `MsgTalkerStop` | Talker on a talk group (protocol ≥ 2 includes TG) |
| 106 | `MsgSelectTG` | Station selects talk group |
| 107 | `MsgTgMonitor` | Station sets monitored talk groups |
| 109 | `MsgRequestQsy` | Request QSY (`0` = reflector chooses) |
| 110–113 | State / signal / TX status | Optional station telemetry |
| 111 | `MsgNodeInfoV2` | JSON node info (protocol 2 body) |
| 114 | `MsgStartUdpEncryption` | Protocol 3: OK to encrypt UDP |

### UDP messages

| Type | Name | Role |
| --- | --- | --- |
| 1 | `MsgUdpHeartbeat` | Keepalive / NAT binding |
| 101 | `MsgUdpAudio` | Encoded audio bytes (no talk-group field in the active class) |
| 102 | `MsgUdpFlushSamples` | End of audio stream |
| 103 | `MsgUdpAllSamplesFlushed` | Peer has flushed |
| 104 | `MsgUdpSignalStrengthValues` | Signal reports over UDP |

The codec name is negotiated in `MsgServerInfo`, not per audio packet. When Opus is available and `CODECS` is unset, the reflector prefers **OPUS**.

## Linking and talk-group sharing

`svxreflector` interconnects **stations** on talk groups. It has no peer-reflector configuration: two reflector processes do not mesh. Upstream has discussed multi-reflector interconnect (GitHub issue #597); it is not shipped in the tree this lab tracks. FM-Funknetz states the same limit and attaches other networks by **talk-group sharing / bridge**—audio continuity on a designated talk-group number, implemented by a **client** present on both sides (typically an extra `svxlink` instance on the server), not by reflector peering.

A Funknetz station only **consumes** a shared talk group (select or monitor it). Creating a bridge on the live network needs coordination with the FM-Funknetz team (loop risk). Named cross-network talk groups in their prose include **2621** (Berlin), **2629** (Sachsen), and possibly **2624**; app ingress paths such as Zello, FRN, and Teamspeak often default to **262**.

| Concept | What it actually is |
| --- | --- |
| Reflector peering | **Unsupported.** Not how you join two Verbünde. |
| `LINKS=` / ReflectorLink | Audio link between logics **inside one** `svxlink` process (e.g. radio ↔ ReflectorLogic). Not two `svxreflector` servers. |
| `MONITOR_TGS` / select TG | Watching or joining a talk group **on one** reflector. Uses a bridge TG if operators already bridge it; does not create the path. |
| EchoLink / Zello / FRN / Teamspeak | Alternate **ingress** into FM-Funknetz. Different protocols; EchoLink cannot switch talk groups. |
| Same reflector, same TG, two stations | Normal conference behavior—not a bridge test. |

To **simulate** sharing locally: run two `svxreflector` instances on distinct ports and users, plus one bridging `svxlink` (two ReflectorLogic sections or two processes) linked so audio crosses on chosen talk groups. Prove with a third station on each side. Exact dual-ReflectorLogic INIs for FM-Funknetz’s production bridge are not published; compose the lab from upstream logic-linking docs.