Host Agent Setup

Overview

Host Agent Setup walks you through installing the DeviceQuest agent on a managed Linux or Windows endpoint. You pick the platform, download the agent, issue a one-time bootstrap credential, and run an install script on the host. The agent enrolls with the credential, which is then used up, and from then on connects outbound to the agent gateway with its own token. Enrolled agents appear on Host agents.

Open it from Admin → Enroll Agent in the sidebar. The old address /admin/windows-agent opens the same page with Windows preselected. The page is for administrators: people without the admin:manage permission see the access-restricted page instead.

Screen tour

Click to enlarge

Two notices can appear above the steps:

• Agent gateway is not enabled for this deployment: you can still issue a credential and download the agent, but agents can enroll only after the deployment administrator enables the agent gateway for this control plane.
• One-command installs are off for this deployment: the page shows the manual install script. On Kubernetes, one-command installs are turned on with the Helm value agentGateway.external.enabled=true, which needs ingress.tlsSecretName. See One-command install.

Choose the target platform

Click to enlarge

Match the host you are enrolling. Every later step, the download and the script follow your choice.

Download the agent

Click to enlarge

The agent connects to the gateway in hybrid or saas mode. When the control plane runs in another mode, for example onprem with the agent gateway enabled, the page uses hybrid and explains why under Why not onprem?.

You need the separate download only for the manual install. The install script downloads the agent itself.

Issue a bootstrap credential

Click to enlarge

1. Enter a Target name.
2. Check the Gateway and Portal download URL. Both are filled in from the address you use, and both must be reachable from the target host, not just from your browser. When one-command installs are on, the deployment sets both and you cannot edit them.
3. Set the Credential lifetime (minutes).
4. Click Issue one-time credential.

The button stays disabled until you enter a target name and a gateway. If the Portal download URL is empty, a warning tells you that the download link and script point at the placeholder portal.example.com.

Click to enlarge

The install script in step 4 now contains the credential, so you can also copy the script instead of the credential alone. Copy the script before you click I’ve saved it.

Bootstrap credential lifetime

A bootstrap credential:

• is valid for the Credential lifetime you chose: from 5 minutes to 1,440 minutes (24 hours), 60 minutes by default. Values outside this range are clamped.
• enrolls one agent. When an agent enrolls with it, the credential is used up and leaves the Active bootstrap credentials list.
• can only enroll. The enrolled agent receives its own token and no longer needs the credential, so the credential expiring later does not affect it.

Issue a new credential for every host, and keep the lifetime short: long enough to run the install, no longer.

Install

Step 4, Run the install script, shows what to run on the target host, for the platform you chose. Click Copy script to copy it. Issue the credential first: until you do, the script contains the placeholder <one-time-agent-credential>.

Linux

Click to enlarge

Run the script on the target Linux host as a user who can use sudo. It:

1. downloads the agent from the Portal download URL to devicequest-agent,
2. runs sudo ./devicequest-agent install with your Gateway, the agent mode and the credential. This copies the agent to /usr/local/bin/devicequest-agent, creates the devicequest-agent system user, writes the settings to /etc/devicequest-agent/agent.env, installs a hardened systemd unit, enrolls the agent and starts the devicequest-agent service,
3. shows the service status with systemctl status devicequest-agent --no-pager.

The agent keeps its state in /var/lib/devicequest-agent. To remove the agent later, run sudo devicequest-agent uninstall; it stops the service and removes the unit and the settings, and keeps the state directory.

Windows

Click to enlarge

Run the script in PowerShell as Administrator on the target Windows machine. It:

1. creates C:\ProgramData\DeviceQuest\Agent and downloads the agent there as devicequest-agent.exe, stopping an existing DeviceQuestAgent service first,
2. registers the DeviceQuestAgent service (display name DeviceQuest Agent, automatic start) with your gateway, mode and credential, and starts it,
3. waits up to 60 seconds for the agent to enroll, then removes the credential from the saved service command and restarts the service. It prints DeviceQuest Agent enrolled. Bootstrap credential removed from the service command.

If enrollment does not finish within 60 seconds, the script warns you to check that the host reaches the gateway and to read the service logs.

One-command install

When the deployment serves the agent itself, step 4 shows a single command instead of a script. The control plane bakes in its public address, the agent gateway and the SHA-256 of each agent build, so you do not enter or check them yourself, and Gateway and Portal download URL in step 3 are read-only.

Linux, run on the target host:

curl -fsSL 'https://dq.example.com/api/v1/agent/install.sh?token=<credential>' | sudo bash

When the DeviceQuest server certificate comes from a private certificate authority, tick The server certificate is from a private CA (I have its ca.pem on the host). The command then becomes:

curl -fsSL --cacert ca.pem 'https://dq.example.com/api/v1/agent/install.sh?token=<credential>' | sudo DEVICEQUEST_AGENT_CA_FILE="$PWD/ca.pem" bash

Windows, run in an elevated PowerShell:

[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12; & ([scriptblock]::Create((Invoke-RestMethod -UseBasicParsing 'https://dq.example.com/api/v1/agent/install.ps1?token=<credential>')))

The command downloads an installer script from the control plane:

Every address needs a valid bootstrap credential in token. A credential that is unknown, revoked, already used or expired gets install command not found or expired; ask your admin for a new one. After the install, follow the Linux agent’s log with sudo journalctl -u devicequest-agent -f.

Active bootstrap credentials

Click to enlarge

The list shows every credential of your organisation that has not been used or revoked, newest first, with its Name, Prefix, Expires, Last used and Status. When there are none, it shows No active bootstrap credentials. If the list cannot be loaded, Could not load bootstrap credentials appears with a Retry button.

Revoke a bootstrap credential

Revoke a credential you issued but no longer need, or one that may have leaked, so nobody can enroll an agent with it.

Click to enlarge

1. Click Revoke on the credential’s row.
2. Check the name in the dialog and click Revoke.

The credential leaves the list and can no longer enroll an agent or download the installer. Revoking cannot be undone; issue a new credential if you need one. Agents that already enrolled keep working: to disconnect one, revoke the agent on Host agents.

Issued and revoked credentials are recorded in the Audit log.

Fields

Statuses

Keyboard shortcuts

Related pages

• Host agents
• Install the agent on Linux
• Install the agent on Windows
• Agent overview
• Scanning overview
• Audit log
• Roles and permissions