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, database or public key files in the destination directories. 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.
Windows x64
cd /d "C:\Program Files\Aspia\Router"
aspia_router --create-config
Linux
sudo aspia_router --create-config
The command creates the configuration file, the database, the keys for Hosts and Relays and the
user admin with the Administrator, Manager and Operator access levels. The password of the user is
generated randomly and is displayed once at the end of the command output:
==================== LOGIN CREDENTIALS ====================
User name: admin
Password: <generated password>
Save the password. It is not shown again.
===========================================================
WARNING! Save the password. It is not stored in clear form and cannot be displayed again.
Use this user for the first connection to the Router from the Client. At the first connection the two-factor authentication of the user is set up. To manage users, use the Router management in the Client.
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 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. |
access_log_days |
Number from 1 to 365, default 45 | The number of days the records of the access log are kept. Older records are deleted automatically. A value outside the range is replaced by the nearest bound. |
Section [host]
| Parameter | Values | Description |
|---|---|---|
listen_interface |
IPv4 or IPv6 address, empty by default | Interface address on which the listener of the Hosts 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. |
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 listener of the Hosts 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 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. |
Section [smtp]
The section contains the parameters of the SMTP server through which the Router sends email notifications to its users. A notification is sent only to a user who has an email address.
| Parameter | Values | Description |
|---|---|---|
server |
Host name or IP address, empty by default | The address of the SMTP server used to send emails. Specify an empty value to disable sending of emails. |
port |
Number from 1 to 65535, default 587 | The TCP port of the SMTP server. |
security |
none, starttls or tls, default starttls |
starttls - the connection is switched to TLS with the STARTTLS command, tls - the connection uses TLS from the start, none - without encryption. An unknown value is replaced by starttls. |
user |
String, empty by default | The user name for authentication on the SMTP server. If the value is empty, authentication is not performed. |
password |
String, empty by default | The password for authentication on the SMTP server. |
from |
Email address, required if server is specified |
The address of the sender of the emails. If the address is not valid, emails are not sent. |
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 |
|---|---|---|
| 8061 | TCP | Hosts |
| 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
Auxiliary databases
Besides the main database the Router keeps auxiliary databases in the same directory:
| File | Contents |
|---|---|
access_log.db3 |
The access log. The retention period of the records is set by the access_log_days parameter of the configuration file. |
email_queue.db3 |
Email notifications waiting to be sent. |
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
The Router writes the log to files. Logging to stdout is disabled by default. The logging parameters are changed by the following environment variables:
- ASPIA_LOG_LEVEL sets the log level with a value from 0 to 4 (0 - trace, 1 - info, 2 - warning, 3 - error, 4 - fatal). Default 1. Decreasing the value increases the number of messages in the log.
- ASPIA_LOG_TO_FILE with a value of 0 disables logging to files.
- ASPIA_LOG_TO_STDOUT with a value other than 0 enables logging to stdout.
- ASPIA_MAX_LOG_FILE_AGE sets the age in days after which the log files are deleted automatically. The variable can take a value from 0 to 366. Default 14. If the variable is set to 0, then the log files are not deleted automatically.
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.
- After changing the configuration files, you must restart the Router service. The Router reads the configuration at startup!