Networking: the DCV gateway and the Billet relay

A deployment can have two kinds of desktop, and each has its own way through your network:

• Billet desktops (Billet Host) use the Billet relay when a session cannot go direct.
• Amazon DCV desktops use your Amazon DCV Connection Gateway, always.

The two never stand in for each other. The relay carries no DCV traffic, and the gateway carries no Billet session. If you have only one kind of desktop, you need only its piece: no gateway for Billet desktops only, and no relay for DCV desktops only.

The difference in one table

The biggest practical difference is the direction. A Billet host makes only outbound connections, so it can sit behind NAT with no rules at all. A DCV desktop has to accept a connection from the gateway, so the gateway must be able to reach it.

Billet relay

person's device --UDP 4444--> relay <--UDP 4444-- Billet host (dials out)
browser tab ----TCP 443-----> relay
portal ---------UDP 4444----> relay   (sets up each session)
relay's agent --TCP 443-----> portal  (check-ins)

The relay does not need a route to your hosts' network. A session can skip the relay and go direct, host to device on UDP 4455, when the tenant allows it and the two can reach each other: see Direct and relayed connections. To set one up, see Install a relay.

DCV Connection Gateway

DCV client ----TCP/UDP 8443--> gateway ----TCP/UDP 8443--> DCV desktop
gateway -------HTTPS---------> portal's DCV listener   (which desktop?)
DCV desktop ---HTTPS---------> portal's DCV listener   (is this session real?)
DCV desktop ---TCP 443-------> portal                  (agent check-ins)

When someone connects to a DCV desktop:

1. The portal gives their DCV client a connection file naming the gateway (BILLET_DCV_GATEWAY_HOST) and a session that is good for 60 seconds.
2. The client connects to the gateway.
3. The gateway asks the portal's DCV listener which desktop holds the session, and connects to that desktop on its private address.
4. DCV Server on the desktop asks the portal's DCV listener whether the session's token is one the portal gave out, and lets the person in only if it is.

Nobody but the gateway needs to reach a DCV desktop. Keep 8443 on the desktops closed to everything else.

The agent turns on DCV's QUIC listener on UDP 8443, and the connection file tells clients to use QUIC, so open UDP 8443 on the gateway as well as TCP. To use TCP only, set BILLET_DCV_TRANSPORT=websocket on the portal.

The gateway's certificate is checked by people's DCV clients, so give it a publicly trusted certificate for the name in BILLET_DCV_GATEWAY_HOST.

The portal's DCV listener

The gateway and DCV Server reach the portal at its own address for DCV, separate from the sign-in pages. It answers only under /dcv/t/<tenant ID>/<secret>/: the address the console's Create the address makes for a tenant. The secret in the path is what admits a caller, so the listener can be on the internet, but there is no reason to show it to anyone except your gateway and DCV desktops.

Add it to the portal's nginx site from Put the portal behind a reverse proxy, with its own name and certificate. Use a name that is not under the portal's name: the portal treats <anything>.portal.example.com as a tenant's address, and refuses DCV requests there.

server {
    listen 443 ssl;
    server_name portal-dcv.example.com;

    ssl_certificate     /etc/letsencrypt/live/portal-dcv.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/portal-dcv.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;

    # To the portal, this is its own name.
    proxy_set_header Host              portal.example.com;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Beam-Zone-Token "";

    # Optional: only your gateway and DCV desktops.
    # allow 203.0.113.0/24;
    # deny  all;

    location /dcv/t/ { proxy_pass http://billet_portal; }
    location /       { return 404; }
}

Get its certificate with sudo certbot --nginx -d portal-dcv.example.com. Use a publicly trusted certificate: DCV Server and the gateway each refuse a listener whose certificate they cannot check.

Then tell the portal, in its service unit, and restart it:

# The listener above. Handed to each DCV desktop's agent.
Environment=BILLET_DCV_PUBLIC_URL=https://portal-dcv.example.com
# The gateway's public name and port, written into each connection file.
Environment=BILLET_DCV_GATEWAY_HOST=dcv-gateway.example.com
Environment=BILLET_DCV_GATEWAY_PORT=8443

Without BILLET_DCV_GATEWAY_HOST, the portal makes no connection file and nobody can open a DCV desktop.

Point the gateway at the portal

The gateway asks the portal where a session is through its resolver setting. The resolver address holds the tenant's secret, and the console never shows it. Read it with the portal's administration API, using an API token from Deployment, API tokens:

curl -fsS -H "Authorization: Bearer <API token>" \
  https://portal.example.com/admin/tenants/<tenant ID>/dcv-capability

The answer has resolver_url. In the gateway's dcv-connection-gateway.conf, set the resolver's url to it, and restart the gateway. Amazon's documentation for the DCV Connection Gateway has the rest of that file. Replace it... in the console changes the secret, and then the gateway needs the new resolver_url, as the desktops' agents get theirs at their next check-in.

Note: The portal sends every DCV session to the one gateway in BILLET_DCV_GATEWAY_HOST, and a resolver address names one tenant. If more than one tenant has DCV desktops, ask Billet how to set up the gateway before you start.

Both on one network

A deployment with both kinds of desktop runs both pieces side by side. A common layout:

The full list of every port is in Network ports.