Skip to content

Relay ​

Ordyn Relay connects Intel AMT KVM and SOL sessions, Microsoft Hyper-V consoles, managed Remote Access, Remote Desktop, and Quick Support. Relay is managed under Services > Relay.

See Desktop Connections for desktop network requirements and connection recovery, and Architecture for the trust model.

Components and network requirements ​

Each deployment requires:

  • an Edge service
  • a public HTTPS/WSS address and valid TLS certificate for the Relay service
SourceDestinationPort and protocolPurpose
BrowserRelay serviceHTTPS/WSS TCP 443Session setup and Intel AMT, Hyper-V console, Remote Access, Remote Desktop, or Quick Support transport
AMT clientRelay serviceWSS TCP 443KVM or SOL device-side data
Hyper-V host AgentRelay serviceWSS TCP 443Hyper-V console device-side data
Windows AgentRelay serviceWSS TCP 443Remote Access and Remote Desktop transport
Quick Support clientRelay serviceHTTPS/WSS TCP 443Invitation redemption, support connection, and recovery
Quick Support RelayOrdyn applicationHTTPS TCP 443Quick Support authorization and session control
Relay serviceAssigned EdgeWSS TCP 443Enrollment, control, and runtime configuration
Relay serviceRedisTCP 6379 by defaultShared authorization and capacity state

The browser and the participating AMT client or Windows Agent initiate WSS connections to the selected Relay service. Relay requires public inbound HTTPS/WSS access and connects outbound to Edge.

See the desktop firewall table for client and endpoint requirements.

Installation ​

Prerequisites:

Open Services > Relay, select Add Relay service client, and configure:

  • a unique name
  • the assigned Edge service
  • the public HTTPS/WSS base URL
  • permitted uses: AMT, Hyper-V, Managed Remote Access, Remote Desktop, and Quick Support

Copy the created Relay service client ID.

Relay service clients have a maximum of 50 channels by default. Set a different maximum when creating or editing a client if needed. The configured limit controls admission; available bandwidth and host resources determine performance.

Enable any combination of permitted uses. A dedicated Quick Support Relay needs only Quick Support selected. Other connection types cannot use it. Enable Quick Support explicitly if this Relay will serve support clients.

Checkout the Relay deployment folder from the Ordyn compose repository:

bash
if [ ! -d /opt/ordyn-compose/.git ]; then
  git clone --filter=blob:none --sparse https://github.com/ordyn-project/compose.git /opt/ordyn-compose
fi
cd /opt/ordyn-compose
git sparse-checkout add relay

Create the environment file:

bash
cd /opt/ordyn-compose/relay
cp .env.example .env

Set these values in .env:

dotenv
SERVICE_DOMAIN=ordyn-relay.example.com
ORDYN_RELAY_EDGE_HOST=ordyn-edge.example.com
ORDYN_RELAY_SERVICE_CLIENT_ID=<service-client-id>

SERVICE_DOMAIN must resolve to the Traefik host. Use the corresponding URL, such as https://ordyn-relay.example.com, as the service client's public HTTPS/WSS base URL.

Pull and verify the service image:

bash
docker compose pull
python3 /opt/cosign-docker-verify/verify.py

Continue only when the Relay image verifies successfully and no failed verification message appears. Open Administration > Enrollment Tokens, choose Service client and Relay, and select the same Edge service and Relay service client. Relay enrollment is global and does not use a tenant. Copy the one-time token, stop any running Relay container, and enroll the persistent service state:

bash
docker compose stop relay
printf '%s' '<enrollment-token>' | docker compose run --rm -T --no-deps relay npm run enroll -- --token-stdin

After enrollment succeeds, start Relay and its required services:

bash
docker compose up -d relay

To renew, recover, or replace the Relay service-client certificate, issue a new token and run forced enrollment while Relay is stopped:

bash
docker compose stop relay
printf '%s' '<enrollment-token>' | docker compose run --rm -T --no-deps relay npm run enroll -- --token-stdin --force

Run docker compose up -d relay only after forced enrollment succeeds. Do not use docker compose exec for enrollment.

Session behavior ​

Assign Relays through Service routing on a tenant or endpoint folder. A folder assignment overrides its parent folders and the tenant. At least one suitable Relay must be available at the effective scope for managed desktop, Hyper-V, or AMT consoles.

Assign multiple Relays at that scope for availability or capacity. Ordyn selects an available Relay that supports the connection type and has free capacity. It does not fall back to a parent scope if all assigned Relays are unavailable. Routing changes apply to new sessions; active sessions keep their Relay.

Quick Support routing and downloads ​

Quick Support uses installation-wide Relays with Quick Support enabled. Each needs a valid public HTTPS address. Configure these before downloading clients from Software → Releases.

Clients can try another configured Relay when one is unavailable. Changes to addresses or enabled uses affect fresh downloads; redistribute the client to update existing copies. See Quick Support for setup and trusted distribution.

Operations and retirement ​

Use the Relay detail page to check connectivity, errors, and channel capacity. Each Remote Access monitor uses a channel, so a session can occupy more than one slot. Bandwidth and host resources also affect performance.

Drain a Relay before retiring it. This prevents new sessions while existing sessions finish. Let sessions end or terminate them, then remove the Relay after resolving its remaining references.