SVXREFLECTOR.CONF(5)

NAME
svxreflector.conf - Configuration file for the SvxReflector conference server audio reflector

DESCRIPTION
The svxreflector server is used to interconnect multiple SvxLink nodes into one network. This man-page describe the configuration file format for it.

SvxReflector look for configuration files in a number of places. First it tries to find a user specific configuration file. It will look for a user specific configuration file in: $HOME/.svxlink/svxreflector.conf. If no user specific configuration file can be found, svxreflector will look for the system wide configuration file /etc/svxlink/svxreflector.conf. The --config command line option may also be used to specify an arbitrary configuration file.

FILE FORMAT
The configuration file is in the famous INI-file format. A generic example of how such a file might look like is shown below.
  [SECTION1]
  VALUE1=1
  VALUE2="TWO "
  VAULE3="Multi "
         "line"

  [SECTION2]
  VALUE1=2 This is a simple format that contain name=value pairs that belong to a section. In written text, a specific configuration variable can be referred to as SECTION1/VALUE2 meaning "configuration variable VALUE2 in section SECTION1".

The same variable name can exist in two different sections. For example VALUE1 in section SECTION1 have the value 1 and VALUE1 in section SECTION2 have the value 2. Values containing spaces at the beginning or end of the line must be surrounded by citation characters (see SECTION1/VALUE2). Likewise with a multi line value (see SECTION1/VALUE3).

CONFIGURATION VARIABLES
Here is the description of all configuration variables that svxreflector understands. The configuration variables are described section for section.

  GLOBAL
The GLOBAL section contains application global configuration data.

CFG_DIR
    Specify the path to a directory that contain additional configuration files. If a relative path is specified, the path will be relative to the directory where the main configuration file is at. All files in the specified directory will be read as additional configuration. Filenames starting with a dot are ignored.

TIMESTAMP_FORMAT
    This variable specifies the format of the timestamp that is written in front of each row in the log file. The format string is in the same format as specified in the strftime(3) manual page. The default is "%c" which is described as: "the preferred date and time representation for the current locale". The environment variables LC_TIME, LC_ALL and LANG will affect how this time format will look. For example, setting LC_TIME="sv_SE.UTF8" will give you Swedish timestamp representation. Other examples of format specifiers are:

    •   %d - The day of the month as a decimal number (range 01 to 31)

    •   %b - The abbreviated month name according to the current locale

    •   %Y - The year as a decimal number including the century

    •   %H - The hour as a decimal number using a 24-hour clock (range 00 to 23)

    •   %M - The minute as a decimal number (range 00 to 59)

    •   %S - The second as a decimal number (range 00 to 61)

    So, TIMESTAMP_FORMAT="%d %b %Y %H:%M:%S" would give a timestamp looking something like: "29 Nov 2005 22:31:59".

LISTEN_PORT
    The TCP and UDP port number to use for network communications. The default is 5300. Make sure to open this port for incoming traffic to the server on both TCP and UDP. Clients do not have to open any ports in their firewalls.

SQL_TIMEOUT
    Use this configuration variable to set a time in seconds after which a clients audio is blocked if he has been talking for too long. The default is 0 (disabled).

SQL_TIMEOUT_BLOCKTIME
    If a client has been talking for longer than the time specified in the SQL_TIMEOUT configuration variable he will not be able to talk again until the time in this configuration variable have elapsed. If not specified, the default is one second.

CODECS
    A comma separated list of allowed codecs. For the moment only one codec can be specified. Choose from the following codecs: OPUS, SPEEX, GSM, S16 (uncompressed signed 16 bit), RAW (uncompressed 32 bit floats). The default is OPUS and you should have a very good reason for changing this since that codec provide both low bandwidth (~20kbps by default) and very good audio quality.

TG_FOR_V1_CLIENTS
    Set which talk group to place protocol version 1 clients in. Without this configuration version 1 clients will not be able to use the reflector since they cannot select a talk group by themselves. Talk groups should normally be configured to start with the ITU-T E.212 Mobile Country Code (MCC) for your country, e.g. 240 for Sweden.

RANDOM_QSY_RANGE
    Specify in which talk group range the reflector server should select random talk groups used when using the QSY functionality. The range is specified using two colon separated values. The first one is the lower limit and the second value is the number of talk groups in the range. As an example, if set to 1239900:100 QSY talk groups will be selected from the range 1239900 to 1239999. The recommended lower range to use is <MCC>9900 where MCC is the ITU-T E.212 Mobile Country Code for your country, e.g. 240 for Sweden.

HTTP_SRV_PORT
    Set which port to use for the HTTP server. The HTTP server can be used to fetch reflector status. No port is set by default. Don't expose this port to the public Internet. There are multiple reasons for that. The built in web server is very simple and could be incompatible with some clients. It has not been audited for security problems so there may be security issues. There is also the risk of some client overwhelming the reflector with requests causing disturbances in the reflector operation. Example: HTTP_SRV_PORT=8080

COMMAND_PTY
    Configure a path for a pseudo tty device to send runtime commands to the svxreflector. The device may be defined as COMMAND_PTY=/dev/shm/reflector_ctrl. See the "COMMAND PTY" section below for more information on how to use the command PTY.

ACCEPT_CALLSIGN
    A regular expression for verifying that a received login callsign has the correct format. The default is to roughly match standard ham radio callsigns. Example: ACCEPT_CALLSIGN="S[A-M]\d[A-Z]{1,3}(?:-[A-Z0-9]{1,3})?"

REJECT_CALLSIGN
    A regular expression for rejecting login callsigns. This can be used to block some specific callsigns or even a whole range of callsigns. No callsigns are rejected by default. Example: REJECT_CALLSIGN="SM0XYZ|SM1ABC|SM2.*"

ACCEPT_CERT_EMAIL
    A regular expression for verifying that email addresses in a received certificate signing requests are valid. If unset, which is the default, all email addresses are accepted. If an invalid email address is received from a node it will be disconnected and an error message will be sent to the node. The following example should accept most email addresses at the same time as detecting most invalid ones. Example: ACCEPT_CERT_EMAIL=""\w+(?:[-._+]\w+)*@\w+(?:\.\w+)*"

CERT_PKI_DIR
    The path to the directory containing PKI (Public Key Infrastructure) files. If a relative path is given, the value of the build time variable SVX_LOCAL_STATE_DIR (e.g. /var/lib/svxlink/) will be prepended. Default: CERT_PKI_DIR=pki/

CERT_CA_KEYS_DIR
    The path to the directory containing private key files. If a relative path is given, the value of the CERT_PKI_DIR variable will be prepended. Default: CERT_CA_KEYS_DIR=private/

CERT_CA_PENDING_CSRS_DIR
    The path to the directory containing unsigned CSR files. If a relative path is given, the value of the CERT_PKI_DIR variable will be prepended. Default: CERT_CA_PENDING_CSRS_DIR=pending_csrs/

CERT_CA_CSRS_DIR
    The path to the directory containing signed CSR files. If a relative path is given, the value of the CERT_PKI_DIR variable will be prepended. Default: CERT_CA_CSRS_DIR=csrs/

CERT_CA_CERTS_DIR
    The path to the directory containing signed certificate files. If a relative path is given, the value of the CERT_PKI_DIR variable will be prepended. Default: CERT_CA_CERTS_DIR=certs/

CERT_CA_HOOK
    Set to a path for an external application that is run on CA events like when a CSR is received or when a certificate is signed. The following environment variables will be set up before running the external application.

    •   CA_OP: Set to one of the strings PENDING_CSR_CREATE, PENDING_CSR_UPDATE or CSR_SIGNED, which should be self explanatory.

    •   CA_CSR_PEM: CSR data in PEM format. This is not set for operation CSR_SIGNED.

    •   CA_CRT_PEM: Certificate data in PEM format. This is only set for operation CSR_SIGNED.

  ROOT_CA, ISSUING_CA and SERVER_CERT sections
These configuration sections is used to customize the contents of the different certificates that is generated by the reflector server.

KEYFILE
    The path to the certificate private key file. If a relative path is given, the value of the CERT_CA_KEYS_DIR variable will be prepended.

CSRFILE
    The path to the certificate signing request file. If a relative path is given, the value of the CERT_CA_CSRS_DIR variable will be prepended.

CRTFILE
    The path to the certificate file. If a relative path is given, the value of the CERT_CA_CERTS_DIR variable will be prepended.

COMMON_NAME
    The common name (CN) used in the subject of the certificate.

ORG_UNIT
    The organizational unit (OU) used in the subject of the certificate. Example: ORG_UNIT="VHF/UHF-sektionen"

ORG The organization name (O) used in the subject of the certificate. Example: ORG=SSA

LOCALITY
    The locality name (L) used in the subject of the certificate. Example: LOCALITY=Boden

STATE
    The name of the state or province (ST) used in the subject of the certificate. Example: STATE=Norrbotten

COUNTRY
    The ISO country code (C) used in the subject of the certificate. Example: COUNTRY=SE

SUBJECT_ALT_NAME
    A comma separated list of subject alternative names. Example: SUBJECT_ALT_NAME=DNS:public-hostname.example.org,IP:172.17.1.42

EMAIL_ADDRESS
    The email address that can be used to get in contact with the owner of the certificate. Example: EMAIL_ADDRESS=sysop@svxlink.example.org

  USERS and PASSWORDS sections
Previously, all users had to be specified in the USERS section. That is not needed anymore for nodes that use a SvxLink version > 1.8.0. Usernames are totally arbitrary but typically the callsign is used. The purpose is to map each username to a password. However, the password is not given directly but instead a reference to the PASSWORDS section is given. It's done like this so that multiple nodes can share a single password.

An example of how the USERS and PASSWORDS sections may look is given below.
  [USERS]
  SM0ABC-1=MyNodes
  SM0ABC-2=MyNodes
  SM1XYZ=SM1XYZ

  [PASSWORDS]
  MyNodes="A very strong password!"
  SM1XYZ="Another very good password?" This will set up SM0ABC-1 and SM0ABC-2 to use the same password specified by MyNodes in the PASSWORDS section. User SM1XYZ have his own password.

  Talkgroup Configuration Sections
It is possible to set configuration parameters that are only applied to one talkgroup. Those parameters are placed in a configuration section named "TG#<talkgroup id>". Example:
  [TG#9999]
  AUTO_QSY_AFTER=300
  ALLOW=S[A-M]\\d.*|LA8PV
  ALLOW_MONITOR=S[A-M]3.*
  SHOW_ACTIVITY=0 The following configuration variables are valid in a talkgroup configuration section.

AUTO_QSY_AFTER
    Set this to the number of seconds after which an automatic QSY to a random talkgroup is requested. This is typically used to keep call channels and wide area channels clear so that stations does not dwell there for too long. Auto QSY is only triggered directly aftar a talker stop event. The default is that auto QSY is disabled (AUTO_QSY_AFTER=0).

ALLOW
    A regular expression that must match the whole callsign of the nodes that try to select this talkgroup. The regular expression standard used is the same as for ECMAScript with the exception that the backslash special patterns (e.g. \s, \d etc) must be expressed with double backslash notation (e.g. \\s, \\d etc). An example that match most Swedish callsigns and a specific Norwegian one is "S[A-M]\\d.*|LA8PV". That expression will for example match LA8PV, SM0SVX, SK3W, SA7ABC etc.

ALLOW_MONTOR
    A regular expression that must match the whole callsign of the nodes that try to monitor this talkgroup. The regular expression standard used is the same as for ECMAScript with the exception that the backslash special patterns (e.g. \s, \d etc) must be expressed with double backslash notation (e.g. \\s, \\d etc). An example that match most Swedish callsigns in district 3 is "S[A-M]3.*". That expression will for example match SA3ABC, SM3XYZ, SK3GK, SH3YZX etc.

SHOW_ACTIVITY
    If set to 0, do not indicate in the http status message when the talkgroup is in use by a node. Default is 1 = show activity.

COMMAND PTY
If a command PTY has been set up using the COMMAND_PTY configuration variable it is possible to use the commands described below to control some functions in the reflector server. The commands can be sent to the PTY by using the following shell command: echo THE COMMAND >/dev/shm/reflector_ctrl Valid commands are:

CFG <section> <tag> <value>
    Read or set configuration. Configuration variables that is set is not persisted so the new setting will be lost on next restart. If the command is used without arguments, the full configuration will be listed. If only a section is given, that section will be listed. If both section and tag is given, only that specific configuration variable will be listed. If in addition a value is given, that specific configuration variable will be set to that value.

NODE BLOCK <callsign> <blocktime seconds>
    Temporarily block a node from being a talker for the given number of seconds. The node will still be able to choose the talkgroup and listen to the audio but will not be able to participate in the QSO. This command is good to use when a node is disturbing a QSO for whatever reason. The blocktime till be reset to the given value each time the node try to send audio to the reflector. Setting a blocktime of 0 will remove the block. The block is also removed if the node disconnects.

CA LS|LSC|LSP|SIGN <callsign>|RM <callsign>
    The CA command is used to manipulate the Certificate Authority part of the reflector server.
    CA LS is used to list all certificates and pending CSRs (Certificate Signing Requests).
    CA LSC and CA LSP are used to list only the certificates or pending CSRs respectively.
    CA SIGN is used to sign a pending CSR for the given callsign. Note that the callsign is case-sensitive.
    CA RM Remove all certificate files associated with the given callsign. Note that it is NOT sufficient to remove the files to stop the given callsign from logging in. If the node already has a valid certificate, it can be used to log in. To stop a node from logging in, use the REJECT_CALLSIGN configuration variable.

FILES

/etc/svxlink/svxreflector.conf
    The system wide configuration file.

~/.svxlink/svxreflector.conf
    Per user configuration file.

/etc/svxlink/svxreflector.d/*
    Additional configuration files. This directory is setup by the CFG_DIR configuration variable.

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(1), svxlink(1), svxlink.conf(5),