Relay Configuration Reference

Configuration methods

Viaalink Relay supports three interchangeable configuration methods:

1. Command-line flags: --option=value (e.g. --domain=relay.example.com).
2. Environment variables: prefixed with VIAALINK_RELAY_ with hyphens replaced by underscores (e.g. VIAALINK_RELAY_DOMAIN=relay.example.com).
3. YAML configuration file: defined in config.yml (e.g. domain: relay.example.com).

Flags take precedence over environment variables, which take precedence over config.yml.

Note: In the tables below, Default shows the compiled binary default when no config.yml or environment variable is provided. The official Docker Compose and ASUSTOR NAS configurations override --ssh-address to :2222, --http-address to :8080, --https-address to :8443, and set --domain to your Relay hostname (for example relay.example.com).

---

Network and listeners

Flag	Environment Variable	Default	Description
--domain	VIAALINK_RELAY_DOMAIN	(set in config.yml, e.g. relay.example.com)	Root domain name for published subdomains
--ssh-address	VIAALINK_RELAY_SSH_ADDRESS	localhost:2222 (:2222 in container/NAS)	Network address and port for client SSH connections
--http-address	VIAALINK_RELAY_HTTP_ADDRESS	localhost:80 (:8080 in container/NAS)	Address and port for HTTP listener
--https-address	VIAALINK_RELAY_HTTPS_ADDRESS	localhost:443 (:8443 in container/NAS)	Address and port for HTTPS listener
--tcp-address	VIAALINK_RELAY_TCP_ADDRESS	(empty)	Address and port for TCP forwarding listener
--redirect-root	VIAALINK_RELAY_REDIRECT_ROOT	true	Redirect root domain requests instead of returning 404
--redirect-root-location	VIAALINK_RELAY_REDIRECT_ROOT_LOCATION	(set in config.yml, e.g. https://viaalink.com)	Target URL for root domain redirects
--welcome-message	VIAALINK_RELAY_WELCOME_MESSAGE	Press Ctrl-C to close the session.	Welcome banner displayed to clients upon connection
--trusted-proxies	VIAALINK_RELAY_TRUSTED_PROXIES	(empty)	Comma-separated list of trusted reverse proxy IPs or CIDRs for X-Forwarded-For
--idle-connection	VIAALINK_RELAY_IDLE_CONNECTION	false	Enable per-stream idle timeouts on proxied traffic (closes idle WebSocket/SSE streams too; leave off unless clients send their own keepalives)
--idle-connection-timeout	VIAALINK_RELAY_IDLE_CONNECTION_TIMEOUT	5s	Duration to wait for activity before closing a connection when --idle-connection is enabled
--config	VIAALINK_RELAY_CONFIG	config.yml	Path to YAML configuration file

---

Domains, routing, and load balancing

Flag	Environment Variable	Default	Description
--bind-random-subdomains	VIAALINK_RELAY_BIND_RANDOM_SUBDOMAINS	true	Enforce randomly assigned subdomains for web services
--bind-random-subdomains-length	VIAALINK_RELAY_BIND_RANDOM_SUBDOMAINS_LENGTH	3	Number of characters in generated random subdomains
--force-requested-subdomains	VIAALINK_RELAY_FORCE_REQUESTED_SUBDOMAINS	false	Force the bound subdomain to be the exact one requested (fails the bind if already in use)
--append-user-to-subdomain	VIAALINK_RELAY_APPEND_USER_TO_SUBDOMAIN	false	Append the authenticated SSH username to bound subdomains
--append-user-to-subdomain-separator	VIAALINK_RELAY_APPEND_USER_TO_SUBDOMAIN_SEPARATOR	-	Separator inserted between subdomain and SSH username
--banned-subdomains	VIAALINK_RELAY_BANNED_SUBDOMAINS	localhost	Comma-separated list of prohibited subdomains
--bind-hosts	VIAALINK_RELAY_BIND_HOSTS	(empty)	Comma-separated list of extra domains clients can bind
--bind-hosts-tls	VIAALINK_RELAY_BIND_HOSTS_TLS	(empty)	Per-domain TLS policy (host=mode[/provider][+wildcard]). Modes: dns, http, none
--bind-root-domain	VIAALINK_RELAY_BIND_ROOT_DOMAIN	false	Allow clients to bind directly to the root domain
--bind-any-host	VIAALINK_RELAY_BIND_ANY_HOST	false	Allow clients to request arbitrary hostnames
--bind-http-path	VIAALINK_RELAY_BIND_HTTP_PATH	true	Allow clients to bind specific URL path prefixes on HTTP routes
--strip-http-path	VIAALINK_RELAY_STRIP_HTTP_PATH	true	Strip the bound URL path prefix before forwarding requests to the client
--http-load-balancer	VIAALINK_RELAY_HTTP_LOAD_BALANCER	false	Allow multiple clients to bind the same HTTP host and balance requests across them
--tcp-load-balancer	VIAALINK_RELAY_TCP_LOAD_BALANCER	false	Allow multiple clients to bind the same TCP port and balance connections across them
--sni-load-balancer	VIAALINK_RELAY_SNI_LOAD_BALANCER	false	Allow multiple clients to bind the same SNI hostname and balance TLS streams across them
--alias-load-balancer	VIAALINK_RELAY_ALIAS_LOAD_BALANCER	false	Allow multiple clients to bind the same TCP alias and balance connections across them

---

Certificates and HTTPS

Flag	Environment Variable	Default	Description
--https	VIAALINK_RELAY_HTTPS	false	Enable direct HTTPS listener
--https-certificate-directory	VIAALINK_RELAY_HTTPS_CERTIFICATE_DIRECTORY	deploy/ssl/	Directory containing custom certificate and key pairs
--https-ondemand-certificate	VIAALINK_RELAY_HTTPS_ONDEMAND_CERTIFICATE	false	Obtain on-demand certificates via Let’s Encrypt
--https-ondemand-certificate-accept-terms	VIAALINK_RELAY_HTTPS_ONDEMAND_CERTIFICATE_ACCEPT_TERMS	false	Accept Let’s Encrypt terms of service
--https-ondemand-certificate-email	VIAALINK_RELAY_HTTPS_ONDEMAND_CERTIFICATE_EMAIL	(empty)	Contact email for Let’s Encrypt certificate expiry notices
--force-https	VIAALINK_RELAY_FORCE_HTTPS	false	Redirect HTTP requests to HTTPS when a certificate is available
--force-all-https	VIAALINK_RELAY_FORCE_ALL_HTTPS	false	Redirect all HTTP requests to HTTPS unconditionally
--caddy-https-enabled	VIAALINK_RELAY_CADDY_HTTPS_ENABLED	false	Drive bundled Caddy for DNS-01 wildcard certificates
--caddy-dns-provider	VIAALINK_RELAY_CADDY_DNS_PROVIDER	(empty)	DNS-01 challenge provider (porkbun, cloudflare, route53, digitalocean, godaddy)
--caddy-acme-email	VIAALINK_RELAY_CADDY_ACME_EMAIL	(empty)	Email address for Caddy Let’s Encrypt account
--caddy-http-port	VIAALINK_RELAY_CADDY_HTTP_PORT	80	Public HTTP port bound by Caddy
--caddy-https-port	VIAALINK_RELAY_CADDY_HTTPS_PORT	443	Public HTTPS port bound by Caddy
--sni-proxy	VIAALINK_RELAY_SNI_PROXY	false	Enable SNI proxying for end-to-end TLS passthrough

---

Authentication, consoles, and security

Flag	Environment Variable	Default	Description
--authentication	VIAALINK_RELAY_AUTHENTICATION	true	Require authentication for connecting SSH clients
--authentication-keys-directory	VIAALINK_RELAY_AUTHENTICATION_KEYS_DIRECTORY	deploy/pubkeys/	Directory storing authorized client SSH public keys
--authentication-password	VIAALINK_RELAY_AUTHENTICATION_PASSWORD	(empty)	Optional global password for SSH authentication
--private-keys-directory	VIAALINK_RELAY_PRIVATE_KEYS_DIRECTORY	deploy/keys	Directory storing server SSH private host keys
--bind-http-auth	VIAALINK_RELAY_BIND_HTTP_AUTH	true	Allow clients to require per-link HTTP basic authentication (user:pass@host:80:localhost:port)
--banned-ips	VIAALINK_RELAY_BANNED_IPS	(empty)	Comma-separated list of banned IP addresses or CIDRs
--whitelisted-ips	VIAALINK_RELAY_WHITELISTED_IPS	(empty)	Comma-separated list of whitelisted IP addresses or CIDRs
--geodb	VIAALINK_RELAY_GEODB	false	Enable GeoIP database for geographic country filtering
--banned-countries	VIAALINK_RELAY_BANNED_COUNTRIES	(empty)	Comma-separated list of banned ISO country codes
--whitelisted-countries	VIAALINK_RELAY_WHITELISTED_COUNTRIES	(empty)	Comma-separated list of allowed ISO country codes
--setup-token	VIAALINK_RELAY_SETUP_TOKEN	(empty)	Access code gating the setup dashboard at /_relay/dashboard
--license-key-file	VIAALINK_RELAY_LICENSE_KEY_FILE	(empty)	Path to offline license.jwt file (also enables /_relay/dashboard and first-boot setup code)
--admin-console	VIAALINK_RELAY_ADMIN_CONSOLE	false	Enable the live traffic inspection console at /_relay/console
--admin-console-token	VIAALINK_RELAY_ADMIN_CONSOLE_TOKEN	(empty)	Authorization code required to open /_relay/console
--service-console	VIAALINK_RELAY_SERVICE_CONSOLE	false	Enable per-route inspection console links for connected clients
--service-console-token	VIAALINK_RELAY_SERVICE_CONSOLE_TOKEN	(empty)	Fixed access code for per-route service consoles (random when empty)

---

Router port forwarding (UPnP and EZ-Router)

Flag	Environment Variable	Default	Description
--upnp-forward-ports	VIAALINK_RELAY_UPNP_FORWARD_PORTS	false	Enable automatic router port mapping via UPnP
--upnp-ssh-external-port	VIAALINK_RELAY_UPNP_SSH_EXTERNAL_PORT	0	External router port for SSH (0 = same as listen port)
--upnp-http-external-port	VIAALINK_RELAY_UPNP_HTTP_EXTERNAL_PORT	0	External router port for HTTP (0 = same as listen port)
--upnp-https-external-port	VIAALINK_RELAY_UPNP_HTTPS_EXTERNAL_PORT	0	External router port for HTTPS (0 = same as listen port)
--upnp-dashboard-port	VIAALINK_RELAY_UPNP_DASHBOARD_PORT	0	External router port for NAS dashboard reverse proxy (e.g. 28080)
--upnp-turn-relay-max-ports	VIAALINK_RELAY_UPNP_TURN_RELAY_MAX_PORTS	32	Largest UDP port range for calls through firewalls to forward automatically via UPnP, one port at a time (0 disables automatic forwarding)
--upnp-ssh-private	VIAALINK_RELAY_UPNP_SSH_PRIVATE	false	Skip UPnP router mapping for the SSH port (keep LAN-only)
--upnp-http-private	VIAALINK_RELAY_UPNP_HTTP_PRIVATE	false	Skip UPnP router mapping for the HTTP port (keep LAN-only)
--upnp-https-private	VIAALINK_RELAY_UPNP_HTTPS_PRIVATE	false	Skip UPnP router mapping for the HTTPS port (keep LAN-only)
--upnp-dashboard-private	VIAALINK_RELAY_UPNP_DASHBOARD_PRIVATE	false	Skip UPnP router mapping for the dashboard port (keep LAN-only)
--upnp-turn-relay-private	VIAALINK_RELAY_UPNP_TURN_RELAY_PRIVATE	false	Skip UPnP router mapping for STUN/TURN ports (keep LAN-only)
--adm-resource-conf	VIAALINK_RELAY_ADM_RESOURCE_CONF	/adm-etc/resource.conf	Path to ASUSTOR ADM service registry

---

Calls through firewalls (STUN/TURN) and NATS

Flag	Environment Variable	Default	Description
--stun-port	VIAALINK_RELAY_STUN_PORT	3478	UDP port for STUN/TURN services (0 to disable)
--turn-realm	VIAALINK_RELAY_TURN_REALM	(empty)	TURN realm identifier (empty = STUN only, no TURN)
--turn-secret	VIAALINK_RELAY_TURN_SECRET	(empty)	Static authentication secret for TURN credential generation
--turn-public-ip	VIAALINK_RELAY_TURN_PUBLIC_IP	(empty)	Public IP address for TURN allocation candidates (required for TURN)
--turn-relay-min-port	VIAALINK_RELAY_TURN_RELAY_MIN_PORT	49152	Start of UDP port range for relayed media streams
--turn-relay-max-port	VIAALINK_RELAY_TURN_RELAY_MAX_PORT	49167	End of UDP port range for relayed media streams
--nats-enabled	VIAALINK_RELAY_NATS_ENABLED	false	Enable embedded NATS server for messaging and HTTP-to-NATS bridging
--nats-port	VIAALINK_RELAY_NATS_PORT	4222	TCP port for the embedded NATS server
--nats-ws-port	VIAALINK_RELAY_NATS_WS_PORT	4223	WebSocket port for the embedded NATS server (for phone clients)
--signalling-enabled	VIAALINK_RELAY_SIGNALLING_ENABLED	true	Offer cloud signalling (/_relay/signal-* endpoints and per-device NATS address-discovery channel). Requires license mode (--license-key-file, device registration); toggleable at runtime from the NATS tab in /_relay/dashboard

---

TCP forwarding

Flag	Environment Variable	Default	Description
--bind-random-ports	VIAALINK_RELAY_BIND_RANDOM_PORTS	true	Force TCP tunnels to bind randomly assigned ports
--port-bind-range	VIAALINK_RELAY_PORT_BIND_RANGE	0,1024-65535	Permitted port range for TCP forwarding
--tcp-aliases	VIAALINK_RELAY_TCP_ALIASES	false	Enable named private TCP aliases (-J jump host forwarding)

---

Logging and privacy

Flag	Environment Variable	Default	Description
--log-to-stdout	VIAALINK_RELAY_LOG_TO_STDOUT	true	Write log records to standard output
--log-to-file	VIAALINK_RELAY_LOG_TO_FILE	false	Write log records to disk file
--log-to-file-path	VIAALINK_RELAY_LOG_TO_FILE_PATH	/tmp/viaalink-relay.log	Destination path for disk log file
--log-to-file-max-size	VIAALINK_RELAY_LOG_TO_FILE_MAX_SIZE	500	Maximum size in megabytes before rotating log files
--log-to-file-max-backups	VIAALINK_RELAY_LOG_TO_FILE_MAX_BACKUPS	3	Number of rotated log backup archives to retain
--log-to-file-max-age	VIAALINK_RELAY_LOG_TO_FILE_MAX_AGE	28	Maximum number of days to retain rotated log files
--log-to-file-compress	VIAALINK_RELAY_LOG_TO_FILE_COMPRESS	false	Compress rotated log archives using gzip
--log-json	VIAALINK_RELAY_LOG_JSON	true	Emit structured JSON log formatting
--log-hash-ips	VIAALINK_RELAY_LOG_HASH_IPS	true	Anonymize client IP addresses with an 8-character SHA-256 hex prefix
--log-usernames	VIAALINK_RELAY_LOG_USERNAMES	false	Include authenticated SSH usernames in connection log entries
--log-level	VIAALINK_RELAY_LOG_LEVEL	info	Log verbosity level (debug, info, warn, error)