Relay Operations and Maintenance

Overview

This guide covers operational best practices for maintaining Viaalink Relay in production, including log management, backup routines, upgrade procedures, and certificate renewal.

Logging and privacy

Viaalink Relay is designed with privacy-first logging defaults suitable for GDPR and enterprise compliance.

Structured JSON logging

By default, the server writes structured JSON logs to standard output:

{"level":"info","time":"2026-10-16T12:00:00Z","message":"Client connected","client_ip":"e3b0c44298fc1c14","service":"myapp","port":2222}

Enable or toggle JSON logging via --log-json=true or in config.yml:

log-json: true
log-to-stdout: true

Log rotation

To output logs to a dedicated file with automated size and age rotation:

log-to-file: true
log-to-file-path: /var/log/viaalink-relay.log
log-to-file-max-size: 500      # Rotate after 500 MB
log-to-file-max-backups: 3     # Keep 3 rotated archives
log-to-file-max-age: 28        # Retain logs for up to 28 days
log-to-file-compress: true     # Compress rotated log files with gzip

IP anonymization

To protect end-user and visitor privacy:

• IP hashing (--log-hash-ips=true): Incoming IPv4 and IPv6 client addresses are hashed with SHA-256 (recording only the first 8 hex characters) before being written to logs.
• Username masking (--log-usernames=false): Client usernames are withheld from log records by default.

Backup and recovery

All state required to restore a Viaalink Relay instance lives in its persistent data directory.

Persistent data folder contents

The data folder contains the following essential assets:

Backup procedure

Create a compressed tar archive of your persistent data folder:

On Linux

sudo tar -czvf viaalink-relay-backup-$(date +%F).tar.gz -C /var/lib viaalink-relay

On Docker Compose

tar -czvf viaalink-relay-docker-backup-$(date +%F).tar.gz data/ Caddyfile docker-compose.yml

On ASUSTOR NAS

In ADM File Explorer, locate the shared folder viaalink-relay-data, right-click, and select Compress, or schedule an automated backup using ADM Backup & Restore.

Recovery procedure

To restore a Relay instance onto a new server:

1. Install the viaalink-relay binary or container on the new machine.
2. Stop the Relay service:
   bash

   sudo systemctl stop viaalink-relay.service

3. Extract the backup archive to the target location:
   bash

   sudo tar -xzvf viaalink-relay-backup-*.tar.gz -C /var/lib/
   sudo chown -R viaalink:viaalink /var/lib/viaalink-relay

4. Start the Relay service:
   bash

   sudo systemctl start viaalink-relay.service

5. Connecting clients will reconnect automatically without SSH host key warnings.

Software upgrades

Linux systemd installations

Standalone Linux binaries are published with the first release — ask contact@viaalink.com for early access.

When replacing an existing binary with a newer release:

1. Stage the updated binary and mark it executable:
   bash

   chmod +x /tmp/viaalink-relay

2. Stop the service:
   bash

   sudo systemctl stop viaalink-relay.service

3. Replace the binary:
   bash

   sudo mv /tmp/viaalink-relay /usr/local/bin/viaalink-relay

4. Start the service:
   bash

   sudo systemctl start viaalink-relay.service

Docker Compose installations

Run the standard Docker upgrade commands:

# Pull updated images
docker compose pull

# Recreate containers
docker compose up -d

ASUSTOR NAS installations

1. In ADM App Central, click ⚙ → Install Manually.
2. Select the updated .apk package and confirm.
3. ADM updates the application while leaving the viaalink-relay-data shared folder intact.

Certificate lifecycle and DNS-01

Viaalink Relay automates TLS certificate provisioning and renewals via Let’s Encrypt.

Automatic renewal

• Certificates are renewed automatically before expiration by Caddy or the built-in ACME manager.
• For standard HTTP-01 challenges, ensure port 80 is forwarded to the server.
• For DNS-01 wildcard certificates, credentials for one of the five supported DNS providers must be configured using the exact environment variables expected by the server:
  • Porkbun (PORKBUN_API_KEY, PORKBUN_API_SECRET_KEY)
  • Cloudflare (CLOUDFLARE_API_TOKEN)
  • Route53 (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION)
  • DigitalOcean (DIGITALOCEAN_API_TOKEN)
  • GoDaddy (GODADDY_API_TOKEN)

Per-domain certificate mode

When serving multiple domains using --bind-hosts, configure the certificate policy per domain:

• dns: Requests wildcard certificates using DNS-01 challenge via your provider’s API.
• http: Obtains single-host certificates using standard HTTP-01 challenge on port 80.
• none: Requests no public certificate, serving plain HTTP on port 80 with no redirect. Ideal when an upstream load balancer or reverse proxy terminates TLS.

Verifying health

Viaalink Relay does not provide a dedicated HTTP health endpoint. Operating health is verified through two distinct checks:

1. SSH listener responsiveness: Confirm port 2222 accepts TCP connections:
   bash

   nc -zv relay.example.com 2222

2. Dashboard responsiveness: Confirm the management interface loads (when --license-key-file is set):
   • Linux / Docker: http://<server-ip>:8080/_relay/dashboard or https://relay.example.com/_relay/dashboard
   • ASUSTOR NAS: https://yourname.myasustor.com:28080/_relay/dashboard