SVXREFLECTOR(1)

📦
version 26.05.1 · 3 versions
, in alpine 3.24, ubuntu resolute, ubuntu stonking

okay bestie, sit down, grab a strawberry 🍓, because this is the manual page for svxreflector, section 1 of the User Manuals, and we are gonna understand it. no cap.

✨ SYNOPSIS ✨

svxreflector [--help] [--version] [--daemon] [--logfile=log file]
[--config=configuration file] [--pidfile=pid file] [--runasuser=user
name]

that's the whole vibe. flags in, server out. 💅

🌈 DESCRIPTION 🌈

The SvxReflector server is literally the group chat host of the SvxLink world — it interconnects a whole bunch of SvxLink nodes into one single network. 🫶

Traffic gets switched around using talk groups, so all the audio that one node sends to the reflector gets retransmitted to every other node that has selected that same talk group. it's giving "everyone in the same room hears you." 👑

⚠️ And here's the rule: only one talker is allowed at a time on each talk group. so if another node starts sending audio while someone's already active, that second node will not interrupt the first talker. periodt. no talking over each other. 🙈

Control messages travel over a TCP/IP connection, and the audio itself is transported via UDP. so bestie, make sure you open up the configured TCP and UDP ports in your firewall for incoming traffic on the server. 🔥 By default the port number is set to 5300 for both TCP and UDP. The clients do not have to open any ports in their firewall — they're just vibing. ✨

Every node must have a unique user ID, typically the callsign. And no, you can't sneak in twice: it is not allowed for a client using the same user ID to connect more than one time to the server. 🚫

The connections are protected using X.509 certificates — see HANDLING X.509 CERTIFICATES below for all the tea. 🎀

On the SvxLink node side, a ReflectorLogic is what connects to the SvxReflector server. The connection to the SvxReflector from other logics in that node can be activated and deactivated using standard logic linking. If you wanna know how to set up a SvxLink node for use with the SvxReflector, go read the svxlink.conf(5) manual page. 📖

The SvxReflector also offers a QSY functionality, which is used to switch all active nodes over to another talk group. Iconic use case: you make a call on a broad talk group — like a big region or the entire country 🌍 — and when the called party answers, a QSY can be performed to a talk group where only the active nodes are included. the reflector may also be configured to initiate an automatic QSY after a specified duration on certain talk groups. automatic. main character energy. 👑

✨ OPTIONS ✨

  • --help — Print a help message and exit. bye bestie 👋
  • --daemon — Start the SvxReflector server as a daemon. 🐧
  • --runasuser — Start SvxReflector as the specified user. The switch to the new user will happen after the log and pid files have been opened. so, order matters, iykyk 💅
  • --logfile=log file — Specify a log file to put all output into. Both stdout and stderr will be redirected to the log file. everything goes in the box 📦
  • --pidfile=pid file — Specify a pid file to write the process ID into.
  • --config=configuration file — Specify which configuration file to use.
  • --version — Print the version of the application.

🎀 HANDLING X.509 CERTIFICATES 🎀

X.509 certificates and TLS — the same technologies used to secure internet connections in general — are used to authenticate nodes connecting to the reflector server. It's a complex technology ngl, but as much as possible has been done to hide that complexity in SvxReflector to make operating the reflector system easy. 🧚

A node owner does not have to understand the certificate technology at all really. but a reflector sysop needs to understand the basics to be able to operate the reflector and to be able to resolve authentication problems. so if that's you: lock in. 👑

🌸 Public-key cryptography & the key pair

The first thing to understand is that public-key cryptography is used. You will see the term PKI in SvxLink, which is short for Public Key Infrastructure.

To use public-key cryptography, a key pair is needed: a secret private key and a non-secret public key. In SvxLink the key pair is stored in a file with the extension ".key".

💀 Those files must be kept secret since anyone that has access to the secret key can act as the rightful owner. guard that file like it's your phone password, fr fr.

🦋 What a certificate actually is

A certificate is nothing but a small amount of information secured using public-key cryptography. That makes it possible to verify that the information in the certificate is valid.

An X.509 certificate always has a start date and an end date. The certificate will only verify as valid when the current time is within those two dates. ⏰

And here's the cute part: when a certificate has less than 1/3 of its lifetime left, the reflector server will renew the certificate automatically. self-care. ✨

Other than that, the most important information in the certificate is the node callsign. An email address is also good to have in the certificate, but only the callsign is required. The callsign is stored in a certificate field called subject Common Name (CN). Certificates in SvxLink are stored in files with the extension ".crt".

💜 CSRs and signing

A certificate is created by signing a Certificate Signing Request (CSR). The CSR is automatically generated by a node and sent to the reflector when needed.

If configured (see CERT_CA_HOOK), the reflector sysop will be notified when a new CSR is received. 🔔

The reflector sysop should then:

  1. verify that the CSR contains the correct information, and
  2. verify that the requesting node has the right to use the given callsign.
😭 The latter task is the hard part, and that procedure needs to be figured out by the reflector sysop. that's on you bestie.

In SvxLink a CSR is stored in a file with the extension ".csr".

🌈 The chain of certificates

The last piece of information that's important to know about X.509 certificates is that a chain of certificates is used to form the secure infrastructure.

In SvxLink there is a root certificate and a signing certificate:

  • The root certificate is used to sign the signing certificate.
  • The signing certificate is used to sign all other certificates — both for the nodes and the server certificate used by the reflector itself. 👑

🍓 Where the PKI files live

In SvxLink, both on the node side and the server side, PKI files are by default stored in the directory /var/lib/svxlink/pki.

  • Nodes store all their PKI files flat in that directory.
  • On the reflector server there is a subdirectory for each type of file: private (for keys), csrs and certs.
  • There also is a pending_csrs subdirectory for incoming CSRs that have not been signed yet. When a CSR has been signed it will be moved to the csrs subdirectory.

✨ Signing a CSR

Signing a CSR on the reflector server is done through a COMMAND_PTY command:

echo CA SIGN callsign > /dev/shm/reflector_ctrl

that's it. one line. slay. 💅

📁 FILES 📁

  • /etc/svxlink/svxreflector.conf — The system wide configuration file. See svxreflector.conf(5) for further details.
  • ~/.svxlink/svxreflector.conf — Per user configuration file. See svxreflector.conf(5) for further details.
  • /etc/svxlink/svxreflector.d/* — Additional configuration files. This directory is setup by the CFG_DIR configuration variable.

🌱 ENVIRONMENT 🌱

  • HOME — Used to find the per user configuration file.

👑 AUTHOR 👑

Tobias Blomberg (SM0SVX) <sm0svx at svxlink dot org>

💀 REPORTING BUGS 💀

Bugs should be reported using the issue tracker at https://github.com/sm0svx/svxlink.

🫶 Questions about SvxLink should not be asked using the issue tracker. Instead use the group set up for this purpose at groups.io: https://groups.io/g/svxlink

🦋 SEE ALSO 🦋

svxreflector.conf(5), svxlink(1), svxlink.conf(5),

and that's the whole page, bestie!! 💖 this lil manual page came to you from Linux, dated MAY 2025, and it's known as SVXREFLECTOR(1). go be a reflector sysop. you got this. 🎀✨🫶

📦 where this page comes from