Viaalink Viaalink
EN NL
Relay Last verified:

Run Relay on Linux

Install and run Viaalink Relay as a systemd service on a dedicated Linux server or VPS.

Overview

This guide explains how to install and configure Viaalink Relay on a Linux server (Ubuntu, Debian, or Rocky Linux) using a systemd service unit.

Prerequisites

  • A Linux server running an x86-64 (amd64) or ARM64 distribution.
  • Root or sudo privileges.
  • A registered domain name pointing at your server’s IP address (see DNS Configuration).
  • Firewall or router rules allowing traffic on ports 2222/tcp, 80/tcp, 443/tcp, and optionally 3478/udp (see Requirements and Network Architecture).

Installation

1. Obtain the binary

Standalone Linux binaries (amd64 and arm64) are published with the first release — ask contact@viaalink.com for early access.

Once you have the viaalink-relay binary on your server, make it executable and move it to your system PATH:

bash
chmod +x viaalink-relay
sudo mv viaalink-relay /usr/local/bin/viaalink-relay

Verify that the binary runs:

bash
viaalink-relay --version

2. Create the system user and directories

Create a dedicated, unprivileged system user and group to run the Relay:

bash
sudo useradd --system --user-group --no-create-home --shell /usr/sbin/nologin viaalink

Create persistent directories for server host keys, authorized public keys, TLS certificates, license files, and configuration:

bash
sudo mkdir -p /var/lib/viaalink-relay/keys
sudo mkdir -p /var/lib/viaalink-relay/pubkeys
sudo mkdir -p /var/lib/viaalink-relay/ssl
sudo mkdir -p /var/lib/viaalink-relay/license
sudo chown -R viaalink:viaalink /var/lib/viaalink-relay
sudo chmod 700 /var/lib/viaalink-relay/keys

3. Create the configuration file

Create an initial configuration file at /var/lib/viaalink-relay/config.yml. Setting license-key-file (or passing --license-key-file) enables the browser setup dashboard at /_relay/dashboard and generates the initial setup code on first boot, even when running under the Free plan:

yaml
domain: relay.example.com
ssh-address: :2222
http-address: :8080
https-address: :8443
authentication: true
bind-random-subdomains: true
log-json: true
log-to-stdout: true
private-keys-directory: /var/lib/viaalink-relay/keys
authentication-keys-directory: /var/lib/viaalink-relay/pubkeys
https-certificate-directory: /var/lib/viaalink-relay/ssl
license-key-file: /var/lib/viaalink-relay/license/license.jwt

Note: Use http-address: :8080 and https-address: :8443 when running behind a reverse proxy (such as Caddy) or router port translation (80 -> 8080, 443 -> 8443). If the Linux host binds ports 80 and 443 directly with AmbientCapabilities=CAP_NET_BIND_SERVICE, set http-address: :80, https-address: :443, https: true, https-ondemand-certificate: true, https-ondemand-certificate-accept-terms: true, and https-ondemand-certificate-email: admin@example.com.

Set appropriate file ownership:

bash
sudo chown viaalink:viaalink /var/lib/viaalink-relay/config.yml
sudo chmod 600 /var/lib/viaalink-relay/config.yml

Systemd service configuration

The Relay server does not ship with a pre-installed systemd service. Below is an example unit file that configures automatic startup, restart on failure, --license-key-file, and file limit tuning.

Create /etc/systemd/system/viaalink-relay.service:

ini
[Unit]
Description=Viaalink Relay Server
After=network.target network-online.target
Wants=network-online.target

[Service]
Type=simple
User=viaalink
Group=viaalink
WorkingDirectory=/var/lib/viaalink-relay
ExecStart=/usr/local/bin/viaalink-relay \
  --config=/var/lib/viaalink-relay/config.yml \
  --domain=relay.example.com \
  --ssh-address=:2222 \
  --http-address=:8080 \
  --https-address=:8443 \
  --private-keys-directory=/var/lib/viaalink-relay/keys \
  --authentication-keys-directory=/var/lib/viaalink-relay/pubkeys \
  --https-certificate-directory=/var/lib/viaalink-relay/ssl \
  --license-key-file=/var/lib/viaalink-relay/license/license.jwt \
  --log-json=true
Restart=always
RestartSec=5s
LimitNOFILE=65535
AmbientCapabilities=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target

Reload the systemd manager configuration, enable the service, and start it:

bash
sudo systemctl daemon-reload
sudo systemctl enable --now viaalink-relay.service

First start and setup page

When --license-key-file is set, the Relay generates an initial setup code on first boot, writes it to /var/lib/viaalink-relay/license/setup-token.txt, and logs it to the systemd journal (Setup dashboard token: <setup-code>).

Inspect the service logs using journalctl or read setup-token.txt to retrieve your setup code:

bash
sudo journalctl -u viaalink-relay.service -n 50 --no-pager
sudo cat /var/lib/viaalink-relay/license/setup-token.txt

Open the browser setup interface over HTTPS (when TLS is configured on your domain):

text
https://relay.example.com/_relay/dashboard?x-authorization=<setup-code>

Or connect directly to the HTTP listener on port 8080:

text
http://<server-ip>:8080/_relay/dashboard?x-authorization=<setup-code>

After the first visit with ?x-authorization=<setup-code>, the browser stores your session cookie and subsequent visits to /_relay/dashboard open directly. From the setup dashboard, you can:

  • Activate your license.jwt file or operate under the Free plan (up to 10 connected devices).
  • Add custom domains and choose TLS validation methods.
  • Authorize connecting client devices by adding public keys.

Verifying server health

Viaalink Relay does not expose a plain HTTP health URL. Server operational health is confirmed when:

  1. The SSH listener on port 2222 responds to connection attempts:
    bash
    nc -zv 127.0.0.1 2222
  2. The browser setup dashboard loads at http://<server-ip>:8080/_relay/dashboard or https://relay.example.com/_relay/dashboard.

Next steps