Aspia Router
Table of contents
- Purpose
- Installing
- Creating a configuration
- Service
- Configuration file
- Ports
- Data base
- Public key
- Logs
- Command line
- Notes
1. Purpose
The Router is the central server of an installation. It gives IDs to the Hosts, stores the list of the computers and the accounts of the users, and allows the peers (Hosts and Clients) to find each other and to agree on how they will bypass NAT. The Router is managed from the Client.
The Router server must have a public IP address. Router and Relay can only work together. Don’t forget to install Relay.
2. Installing
Windows x86_64
Run aspia-router-<version>-x86_64.msi and follow the instructions on the screen.
Ubuntu
sudo apt install ./aspia-router-<version>-x86_64.deb
RHEL and compatible
sudo dnf install ./aspia-router-<version>-x86_64.rpm
The package installs the files of the Router. To make the Router 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 or database in the destination directory. The Router 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.
WARNING! Default username and password: admin/admin. Don’t forget to change this after installation! To manage users, use the Router management in the Client.
Windows x64
cd /d "C:\Program Files\Aspia\Router"
aspia_router --create-config
Linux
sudo aspia_router --create-config
4. Service
The service is registered after the configuration has been created. Administrator rights are required to execute the commands below.
Windows
aspia_router --install
Linux
sudo aspia_router --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_router --start
aspia_router --stop
Linux
sudo aspia_router --start
sudo aspia_router --stop
The service runs under a low-privilege account that is created during the installation. It has
access only to the directories of the Router.
5. Configuration file
The configuration file contains parameters that do not change while the application is running.
Important! Perform regular configuration file backups to avoid the risk of data loss.
The Router configuration file is located in the following paths:
Windows
C:\ProgramData\aspia\router.conf
Linux
/etc/aspia/router.conf
The path can be changed by the environment variable ASPIA_ROUTER_CONFIG_FILE. The file contains the
private keys of the Router.
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 |
|---|---|---|
seed_key |
128 hexadecimal characters (64 bytes) | It is automatically generated when the configuration is created. Do not change this setting unless you really need to. |
Section [host]
| Parameter | Values | Description |
|---|---|---|
listen_interface |
IPv4 or IPv6 address, empty by default | Interface address on which the listener of the Hosts (both ports) accepts connections. Specify an empty value to listen on all interfaces. If the value is not a valid address, this listener is not started. |
port |
Number from 1 to 65535, default 8061 | The TCP port for Hosts of version 3.0.0 and above. |
legacy_port |
Number from 1 to 65535, default 8060 | The TCP port for Hosts of versions below 3.0.0. |
private_key |
Hexadecimal string, required | The private key used for connections with Hosts. It is automatically generated when the configuration is created. Without it the listeners of the Hosts are not started. Do not change this setting unless you really need to. |
white_list |
Addresses separated by commas, empty by default | The list of Hosts who are allowed to connect to the Router. |
Section [client]
| Parameter | Values | Description |
|---|---|---|
listen_interface |
IPv4 or IPv6 address, empty by default | Interface address on which the listener of the Clients accepts connections. Specify an empty value to listen on all interfaces. If the value is not a valid address, this listener is not started. |
port |
Number from 1 to 65535, default 8062 | The TCP port for Clients. |
white_list |
Addresses separated by commas, empty by default | The list of Clients who are allowed to connect to the Router. |
Section [relay]
| Parameter | Values | Description |
|---|---|---|
listen_interface |
IPv4 or IPv6 address, empty by default | Interface address on which the listener of the Relays accepts connections. Specify an empty value to listen on all interfaces. If the value is not a valid address, this listener is not started. |
port |
Number from 1 to 65535, default 8063 | The TCP port for Relays. |
private_key |
Hexadecimal string, required | The private key used for connections with Relays. It is automatically generated when the configuration is created. Without it the listener of the Relays is not started. Do not change this setting unless you really need to. |
white_list |
Addresses separated by commas, empty by default | The list of Relays who are allowed to connect to the Router. |
Section [stun]
| Parameter | Values | Description |
|---|---|---|
listen_interface |
IPv4 or IPv6 address, empty by default | Interface address on which the built-in STUN server accepts requests. Specify an empty value to listen on all interfaces. If the value is not a valid address, this listener is not started. |
enabled |
1 or 0 (true or false), default 1 |
Enables the built-in STUN server. It is used by Clients and Hosts to determine their external addresses when a direct connection is established. |
port |
Number from 1 to 65535, default 8065 | The UDP port of the built-in STUN server. |
White lists. A white list can contain IP addresses and subnets separated by commas, for example
192.168.1.10,10.0.0.0/8. If the list is empty, then connections from all peers of this type are
allowed. If the list contains items, then only the peers specified in it can connect. Entries that
are neither a valid address nor a valid subnet are ignored.
6. Ports
The Router listens on several ports. Each type of a peer has its own listener:
| Port | Protocol | Purpose |
|---|---|---|
| 8060 | TCP | Hosts of versions below 3.0.0 |
| 8061 | TCP | Hosts of version 3.0.0 and above |
| 8062 | TCP | Clients |
| 8063 | TCP | Relays |
| 8065 | UDP | Built-in STUN server |
The Router does not add rules to the firewall automatically.
7. Data base
The database file contains information about users, workspaces and issued IDs for Hosts. Currently the sqlite database is used.
Important! Perform regular database file backups to avoid the risk of data loss.
The database file is located in the following paths:
Windows
C:\ProgramData\aspia\router.db3
Linux
/var/lib/aspia/router.db3
8. Public key
The Router uses two pairs of keys: one for Hosts and one for Relays. The contents of the public key files are needed to configure Hosts and Relays.
The public key files are located in the following paths:
Windows
C:\ProgramData\aspia\host.pub
C:\ProgramData\aspia\relay.pub
Linux
/etc/aspia/host.pub
/etc/aspia/relay.pub
9. Logs
By default the Router writes the log to files. To configure the Router 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_router-*.log
Linux
/var/log/aspia/router/aspia_router-*.log
If logging to stdout is enabled on Linux, the log can be viewed with the command:
sudo journalctl -u aspia-router
10. Command line
The Router supports the following command line arguments:
| Argument | Description |
|---|---|
--install |
Installs the Router 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 Router service. A running service is stopped before the removal. Administrator rights are required to execute. |
--start |
Starts the Router service. Administrator rights are required to execute. |
--stop |
Stops the Router service. Administrator rights are required to execute. |
--keygen |
Generates a pair of private and public keys and displays them in the terminal. Running the command does not affect the current configuration. |
--create-config |
Creates an initial configuration, the data base and the keys. Administrator rights are required to execute. |
--reset-otp <user> |
Resets the two-factor authentication of the specified user. At the next connection the user passes the enrollment again. 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. |
11. Notes
- Hosts and Relays connect to the Router using a public key. Hosts use the key from
host.pub, Relays use the key fromrelay.pub. - Clients connect using a username, a password and a code of two-factor authentication.
- It is recommended that you set up regular backups of your configuration files and database.
- Don’t forget to add rules in your firewall to access the Router. The Router does not add rules automatically.
- It is recommended to limit the list of Relays that can be connected to the Router. Whitelist the required Relays.
- When uninstalling, the Router does not delete its configuration files and database.
- When updating the Router, do not forget to back up the configuration files and database. The configuration of version 2.7 is migrated automatically, see Migration from version 2.7.
- After changing the configuration files, you must restart the Router service. The Router reads the configuration at startup!