Access Control and Security

Access control model

Viaalink Relay provides multi-layered access control to regulate both who can publish through your Relay server and who can access published addresses.

The security model is built on four core capabilities:

1. Approved device keys (controlling which client machines can connect).
2. Password protection per link (HTTP basic authentication on individual published addresses).
3. Registration invites (onboarding authorized client devices).
4. IP and country filtering (network-level allow and block lists).

Note: Viaalink Relay does not provide single sign-on (SSO) integrations or request rate limiting. Authentication and access decisions are evaluated locally at connection time.

1. Approved device keys

By default, Viaalink Relay requires public key authentication for all incoming SSH connections (--authentication=true).

Client machines authenticate using standard SSH keypairs (such as Ed25519 or RSA).

Adding public keys

Authorized public keys are stored in your server’s public keys directory:

• Linux: /var/lib/viaalink-relay/pubkeys/
• Docker Compose: ./data/pubkeys/
• ASUSTOR NAS: viaalink-relay-data/pubkeys/

Add a client’s public key by copying their .pub file into this directory:

sudo cp ~/.ssh/id_ed25519.pub /var/lib/viaalink-relay/pubkeys/developer-alice.pub

The Relay server actively monitors this folder and hot-reloads keys every 200ms. New keys are accepted immediately without restarting the service or interrupting existing sessions. To revoke access, simply delete the user’s public key file.

Generating keys from the setup dashboard

Operators can also manage client keys directly from the Users tab on the browser dashboard (/_relay/dashboard):

• Click Add Public Key to paste an existing public key.
• Click Generate & download private key to create a fresh Ed25519 keypair. The private key file is downloaded directly to your browser and is never stored on the Relay server.

2. Password protection per link

When --bind-http-auth=true is enabled on the Relay server (the default), individual published HTTP links can be protected with HTTP basic authentication credentials passed in the SSH reverse forward bind host specification (user:password@subdomain:80:localhost:port):

ssh -p 2222 -R admin:SecretPass123@myapp:80:localhost:3000 relay.example.com

Visitors opening https://myapp.relay.example.com are prompted by their browser for HTTP basic authentication credentials (admin / SecretPass123) before any request reaches the forwarded local application.

Server operators can disable per-link HTTP basic authentication across the server by setting --bind-http-auth=false (bind-http-auth: false in config.yml).

3. Invites and registration codes

When onboarding new client devices or team members, operators can generate registration invite codes through the dashboard. A device presenting a valid invite code is granted access to publish services according to the server’s policy.

4. IP and country filtering

Viaalink Relay evaluates IP and geographic rules across all incoming HTTP, TCP, and SSH connections.

Banning specific IP addresses

To deny access from abusive IP addresses or subnets:

# In config.yml
banned-ips: 203.0.113.50,198.51.100.0/24

Or via CLI flag:

viaalink-relay --banned-ips=203.0.113.50,198.51.100.0/24

Whitelisting IP addresses

To restrict your Relay exclusively to trusted networks:

whitelisted-ips: 192.0.2.0/24,198.51.100.12

When an IP whitelist is defined, all unlisted external addresses are blocked.

Important: The server automatically exempts loopback traffic (127.0.0.1, ::1) from external IP whitelists so administrators cannot accidentally lock themselves out of the web dashboard.

Country-based filtering

Country rules allow you to allow or block traffic based on the connecting client’s geographical location.

Country filtering requires the --geodb=true flag to enable IP-to-country resolution:

geodb: true
banned-countries: CN,RU
whitelisted-countries: NL,BE,DE

Private address exemption

Local network addresses—including loopback (127.0.0.0/8, ::1), RFC 1918 private subnets (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), RFC 6598 carrier-grade NAT, and IPv6 unique-local addresses—are strictly exempt from country filtering rules.

This ensures that whitelisting a specific country will never block access from machines on your local office network or home LAN.

TLS termination

By default, TLS is terminated at the Relay server (or fronting reverse proxy such as Caddy):

• Visitor to Relay: Encrypted using HTTPS with Let’s Encrypt certificates.
• Relay to connecting device: Encrypted inside an SSH reverse tunnel.
• Local machine: Traffic is forwarded locally to your application port (e.g. localhost:3000).

To achieve end-to-end TLS passthrough where certificates are managed directly on the backend client application, enable SNI proxy mode using --sni-proxy=true.