Aspia Relay
Table of contents
1. Purpose
Passes traffic between peers (Hosts and Clients) through itself. The Relay server must have a public IP address. There can be a lot of Relay and they can be placed on separate machines from Router. The number of Relay servers can be from one or more. You must install at least one Relay server. Router and Relay can only work together.
2. Installing
Windows x86_64
Run aspia-relay-<version>-x86_64.msi and follow the instructions on the screen.
Ubuntu
sudo apt install ./aspia-relay-<version>-x86_64.deb
RHEL and compatible
sudo dnf install ./aspia-relay-<version>-x86_64.rpm
The package installs the files of the Relay. To make the Relay ready for work, create the
configuration and register the service as described below.
3. Creating a configuration
WARNING! There must be no existing configuration file in the destination directory. The Relay never overwrites the current configuration and creating a new configuration is possible only if the previous one does not exist.
WARNING! Administrator rights are required to create a configuration.
Windows x86
cd /d "C:\Program Files (x86)\Aspia\Relay"
aspia_relay --create-config
Windows x64
cd /d "C:\Program Files\Aspia\Relay"
aspia_relay --create-config
Linux
sudo aspia_relay --create-config
The created configuration contains the default values only. Before starting the service you have to
specify the address of the Router, its public key and the address of the Relay for peers.
4. Service
The service is registered after the configuration has been created. Administrator rights are required to execute the commands below.
Windows
aspia_relay --install
Linux
sudo aspia_relay --install
The service is registered and enabled at the system startup. On an upgrade the package refreshes the
already registered service itself.
To start and stop the service, use the following commands:
Windows
aspia_relay --start
aspia_relay --stop
Linux
sudo aspia_relay --start
sudo aspia_relay --stop
The service runs under a low-privilege account that is created during the installation. It has
access only to the directories of the Relay.
5. Configuration file
Important! Perform regular configuration file backups to avoid the risk of data loss.
The Relay configuration file is located in the following paths:
Windows
C:\ProgramData\aspia\relay.conf
Linux
/etc/aspia/relay.conf
The path can be changed by the environment variable ASPIA_RELAY_CONFIG_FILE.
The file has the ini format: the parameters are grouped into sections. The description of the
sections and their parameters is given below.
Section [router]
| Parameter | Values | Description |
|---|---|---|
address |
Host name or IP address, 127.0.0.1 by default | The address at which the Relay connects to the Router. It can be equal to localhost (or 127.0.0.1) if the Router is installed on the same computer. The Relay does not work with an empty value. |
port |
Number from 1 to 65535, default 8063 | The port of the Router for Relays. If you did not change the port in the Router configuration file, then the parameter must be left with the default value. |
public_key |
Hexadecimal string, required | The public key of the Router. Enter here the key that is contained in the file relay.pub, which is created by the Router. |
Section [peer]
| Parameter | Values | Description |
|---|---|---|
listen_interface |
IPv4 or IPv6 address, empty by default | Interface address on which the server will listen for incoming connections. Specify an empty value if you want to listen for connections on all interfaces. If the value is not a valid address, the Relay does not accept connections from peers. |
public_address |
Host name or IP address, required | The address that peers will receive to connect to the Relay. See the warning below. |
port |
Number from 1 to 65535, default 8070 | The port through which peers will connect to the Relay. |
idle_timeout |
Number of minutes from 1 to 60, default 5 | If during this time no data comes from the peers, the connection is terminated. A value outside of this range stops the Relay from serving peers. |
max_count |
Number from 1 to 1000, default 100 | The maximum number of simultaneous connections established between peers. A greater value is reduced to 1000. |
WARNING! The address specified in public_address must be accessible to all participants in the
connection (Client and Host). You should keep in mind that both peers must be able to connect to this
address. Consider this when setting up your network hardware if you are setting up port forwarding on
your network router. If your network router is behind NAT, then you must provide access to this address
for external and internal connections. See the documentation for your network equipment for more
information on how to do this.
6. Logs
By default the Relay writes the log to files. To configure the Relay logging parameters, use the following recommendations:
- To set the log level, declare an environment variable ASPIA_LOG_LEVEL with a value from 0 to 4 (0 - trace, 1 - info, 2 - warning, 3 - error, 4 - fatal). Decreasing the value increases the number of messages in the log.
- To enable logging to a file (if it is not enabled by default for platform), declare environment variable ASPIA_LOG_TO_FILE with a value other than 0. If the environment variable is declared with a value of 0, then logging to file will be disabled.
- To enable logging to stdout (if it is not enabled by default for platform), declare environment variable ASPIA_LOG_TO_STDOUT with a value other than 0. If the environment variable is declared with a value of 0, then logging to stdout will be disabled.
- By default, log files older than 14 days are automatically deleted. If you want to change this value, then declare environment variable ASPIA_MAX_LOG_FILE_AGE with a numeric value in days. The variable can take a value from 0 to 366. If the variable is set to 0, then the log files will not be automatically deleted.
The log files are located in the following paths:
Windows
C:\ProgramData\aspia\logs\aspia_relay-*.log
Linux
/var/log/aspia/relay/aspia_relay-*.log
If logging to stdout is enabled on Linux, the log can be viewed with the command:
sudo journalctl -u aspia-relay
7. Command line
The Relay supports the following command line arguments:
| Argument | Description |
|---|---|
--install |
Installs the Relay service and enables its start at the system startup. If the configuration does not exist yet, the service is not installed. Administrator rights are required to execute. |
--remove |
Removes the Relay service. A running service is stopped before the removal. Administrator rights are required to execute. |
--start |
Starts the Relay service. Administrator rights are required to execute. |
--stop |
Stops the Relay service. Administrator rights are required to execute. |
--create-config |
Creates an initial configuration. Administrator rights are required to execute. |
--check-update |
Checks for an update and displays the available version. |
--install-update |
Downloads and installs the available update. Administrator rights are required to execute. |
--update-channel <channel> |
The channel for --check-update and --install-update: stable, beta or alpha. Default stable. |
--version |
Displays the version of the application. |
--help |
Displays help about command line arguments. |
8. Notes
- Don’t forget to add rules in your firewall to access the Relay. The Relay does not add rules automatically.
- When uninstalling, the Relay does not delete its configuration files.
- After changing the configuration files, you must restart the Relay service. The Relay reads the configuration at startup!
- The configuration of version 2.7 is migrated automatically, see Migration from version 2.7.