SVXREFLECTOR(1)

NAME
svxreflector - The SvxLink conference server audio reflector

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

DESCRIPTION
The SvxReflector server is used to interconnect multiple SvxLink nodes into one network. Traffic is switched using talk groups in the SvxReflector server so that all audio sent to the reflector from one node is retransmitted on all other nodes that have selected the same talk group. Only one talker is allowed at a time on each talk group so if another node starts sending audio when another one is already active, the second node will not interrupt the first talker.

A TCP/IP connection is used for the control messages and the audio is transported via UDP. Make sure to 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. Each node must have a unique user ID, typically the callsign. 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 by using X.509 certificates. See HANDLING X.509 CERTIFICATES below for more info.

On the SvxLink node side, a ReflectorLogic is used to connect to the SvxReflector server. The connection to the SvxReflector from other logics in that node can be activated and deactivated using standard logic linking. Read more about how to set up a SvxLink node for use with the SvxReflector in the svxlink.conf(5) manual page.

The SvxReflector offer a QSY functionality which is used to switch all active nodes to another talk group. This can be used to make a call on a broad talk group, like a large 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.

OPTIONS

--help
    Print a help message and exit.

--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 has been opened.

--logfile=log file
    Specify a log file to put all output into. Both stdout and stderr will be redirected to the log file.

--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 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 need to understand the basics to be able to operate the reflector and to be able to resolve authentication problems.

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 have access to the secret key can act as the rightful owner.

A certificate is nothing but a small amount of information secured using public-key cryptography. That make it possible to verify that the information in the certificate is valid. An X.509 certificate always have a start date and an end date. The certificate will only verify as valid when the current time is within those two dates. When a certificate has less than 1/3 of its lifetime left the reflector server will renew the certificate automatically. 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".

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 verify that the CSR contains the correct information and 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. In SvxLink a CSR is stored in a file with the extension ".csr".

The last piece of information that is important to know about X.509 certificates is that a chain of certificates are 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.

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 are 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 on the reflector server is done through a COMMAND_PTY command:

  echo CA SIGN callsign > /dev/shm/reflector_ctrl

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),