Set up a Linux Amazon DCV desktop

This guide sets up a Linux machine as an Amazon DCV desktop, which people open with the DCV client, not the Billet app. For a Linux desktop people open with the Billet app, see Billet Host on Linux. Here the machine runs Amazon DCV Server and the Billet stats agent, and people open it with the DCV client through your DCV Connection Gateway after signing in to Billet. Your portal serves an installer that sets up both, enrolls the machine, and starts the agent at every boot.

Before you start

• The machine: 64-bit x86 Linux, with curl, ip and one of apt-get, dnf or yum, and outbound HTTPS to your portal. A desktop environment such as GNOME, for DCV's virtual sessions; see Amazon's DCV documentation for the desktops and distributions DCV Server supports. A GPU and its driver, if the desktop is to use one.
• The network: your DCV Connection Gateway can reach the machine on its private address.
• DCV licensing: outside AWS, DCV Server needs a license from Amazon's license server.
• The portal:
  • It serves the Linux agent: step 5 and BILLET_AGENT_DIST_DIR in Install the portal.
  • The tenant has its DCV address: step 1 of Add an Amazon DCV desktop.
• Accounts: each person who will use the desktop has a Linux account on the machine. Billet runs their session as that account.

1. Register the desktop

1. In the console, open Desktops, Register a desktop, and choose Connects with: Amazon DCV.
2. Fill in DCV server address: the address your gateway reaches this machine at.
3. On the desktop's page, create its enrollment token. It is shown once and works once, so copy it now. See Register a desktop and create an enrollment token.

You also need the tenant's ID: the one you gave when you created the tenant.

2. Download the installer and read it

The installer's address is your portal, the tenant's ID and the token:

curl -fsSL "https://portal.example.com/i/<tenant ID>/<token>?os=linux" -o billet-install.sh
less billet-install.sh

Downloading it does not use up the token; only enrolling does. The file is a short shell script with your portal's address and the token written into it. Keep it on the machine for updates (see below); the token in it stops working once the machine has enrolled.

If curl prints an error instead:

3. Run it

sudo bash billet-install.sh

It does four things, and says each as it goes:

1. Works out the address the gateway will reach this machine at, from its default route, and prints it.
2. Installs Amazon DCV Server, unless it is installed already.
3. Installs the Billet stats agent as /usr/local/bin/billet-stats-agent and enrolls the machine with the token.
4. Installs and starts the billet-agent service, which runs at every boot.

Check the address it prints against the DCV server address you registered. If they differ (the gateway reaches the machine through NAT, or by a name), run it again with the right one:

sudo BEAM_DCV_SERVER_HOST=10.0.0.5 bash billet-install.sh

When it is done it prints billet: done.

If it stops

The installer is safe to run again after any of these. It skips what is already done.

4. Check it worked

On the machine:

systemctl status billet-agent
journalctl -u billet-agent -f

The service is active (running). In the console, the desktop shows on Desktops within a minute. At its first check-in the agent sets DCV Server up to check each connection with the portal, and adds the license file if the tenant has one.

5. Assign it

Assign the desktop to its owner. For Account on the desktop, give their Linux account name on this machine.

At its next check-in, the agent creates a DCV virtual session owned by that account, so their first connect works. Billet does not use the physical console's desktop on Linux unless you ask it to (see below).

Update the agent

Run the installer again. A machine that is already enrolled keeps its identity, skips enrolling, and gets the portal's current agent, so the script from the first install still works even though its token is used. (Downloading a new copy needs a token that has not been used.) Upgrade the portal first, so the agent it hands out is the new one.

Share the physical desktop instead

To have Billet use the machine's own console session rather than a virtual one, set BILLET_DCV_SESSION_TYPE=console for the agent with a systemd drop-in, which the installer leaves alone when it runs again:

sudo systemctl edit billet-agent

Add, then save:

[Service]
Environment=BILLET_DCV_SESSION_TYPE=console

Then sudo systemctl restart billet-agent.

Remove it

sudo systemctl disable --now billet-agent
sudo rm /etc/systemd/system/billet-agent.service /usr/local/bin/billet-stats-agent
sudo systemctl daemon-reload

That leaves the machine's credential (agent-credential.json, in /etc/billet or /etc/beam) and DCV Server. Delete the credential to remove every trace, after which the machine needs a new token to come back. Remove DCV Server with your package manager if nothing else uses it.

Then, in the console, delete the desktop from its page with Delete desktop..., or keep it to enroll a replacement machine into.

Files