Installing the host agent and OTel Collector

Install the host agent (acp-host-agent) on every WarehousePG (WHPG) cluster node to enable privileged operations on behalf of WEM. These operations include editing pg_hba.conf through the HBA Editor tab, running cluster management actions, taking and restoring backups, and collecting host metrics and logs through the node's OTel Collector, all without direct shell access to cluster hosts.

Downloading and installing the host agent

Run these steps from the coordinator as gpadmin.

1. On the coordinator, download the host agent package and its edb-otelcol dependency from the EDB repository:

   → WrapCopy

   export EDB_SUBSCRIPTION_TOKEN=<your-token>
   export EDB_REPO=gpsupp
   curl -1sSLf "https://downloads.enterprisedb.com/$EDB_SUBSCRIPTION_TOKEN/$EDB_REPO/setup.rpm.sh" | sudo -E bash
   sudo dnf download edb-acp-host-agent edb-otelcol

   The host agent depends on edb-otelcol, so download both packages. Installing both .rpm files together on each host lets dnf resolve that dependency locally, without needing the EDB repository configured on every node.

2. On the coordinator, create a file all_hosts, which lists all hosts in the WHPG cluster. For example:

   → WrapCopy

   cdw
   scdw
   sdw1
   sdw2
   sdw3

3. From the coordinator, transfer both downloaded packages to every host in the cluster. Use the gpsync utility on WarehousePG 7, or the gpscp utility on WarehousePG 6:

   • WHPG 7
   • WHPG 6

   → WrapCopy

   gpsync -f all_hosts edb-acp-host-agent-*.rpm edb-otelcol-*.rpm =:/tmp

   → WrapCopy

   gpscp -f all_hosts edb-acp-host-agent-*.rpm edb-otelcol-*.rpm =:/tmp

4. From the coordinator, use gpssh to install both packages together on every host:

   → WrapCopy

   gpssh -f all_hosts -u gpadmin -e "sudo dnf install -y /tmp/edb-acp-host-agent-*.rpm /tmp/edb-otelcol-*.rpm"

5. On every node, set WEM_CONNECT_ADDRESS in /etc/edb/acp-host-agent/acp-host-agent.conf to WEM's IPv4 address and listen port plus 1 (default 8081):

   → WrapCopy

   WEM_HOST=<wem-host-ipv4>
   gpssh -f all_hosts -u gpadmin -e \
     "sudo sed -i 's/^WEM_CONNECT_ADDRESS=.*/WEM_CONNECT_ADDRESS=${WEM_HOST}:8081/' \
       /etc/edb/acp-host-agent/acp-host-agent.conf"

   For the full variable reference, including agent identity and logging, see Host agent configuration.

6. Enable and start the host agent service on every node:

   → WrapCopy

   gpssh -f all_hosts -u gpadmin -e "sudo systemctl enable --now acp-host-agent"

7. Verify each agent self-registered and is waiting for approval:

   → WrapCopy

   gpssh -f all_hosts -u gpadmin -e "sudo cat /var/log/edb/acp-host-agent/acp-host-agent.log"

   Expected output includes:

   → WrapCopy

   INFO self-registration succeeded task_queues=coordinator-tasks
   INFO starting host-agent agent_id=... connect_address=... task_queues=coordinator-tasks
   INFO awaiting TLS material — an admin must approve this agent in wem agent_id=...

   An agent stays in this pending state, repeating the last line, until an Admin approves it. It doesn't reach a running state on its own.

8. Open WEM in a browser, log in with admin credentials, navigate to Management > Host Agents, select the pending agents, and choose Approve from the quick actions. You can confirm you're approving the agent you expect by comparing its Verification Token against the join token on the host (cat /etc/edb/acp-host-agent/join-token).

   Note

   Permission to approve host agent access is disabled by default, even for the Admin profile. To grant this permission, see Defining role-based access control.

9. Once approved, each agent picks up its TLS material and starts its worker within moments. Verify this on any node:

   → WrapCopy

   gpssh -f all_hosts -u gpadmin -e "sudo tail -5 /var/log/edb/acp-host-agent/acp-host-agent.log"

   Expected output includes:

   → WrapCopy

   INFO handlers registered  task_kinds=[file.pull, file.push, otel.service.start, ...]
   INFO connecting to Temporal connect_address=... task_queues=coordinator-tasks
   INFO worker running       task_queue=coordinator-tasks

   WEM pushes the OTel configuration to the host agent and WEM's internal certificate authority issues the agent a short-lived certificate. Every subsequent connection between that agent and WEM authenticates with mutual TLS (mTLS). WEM renews the certificate automatically, with a 24-hour grace window that lets an agent that was briefly offline recover its certificate without Admin intervention.

Next steps

Your installation is complete. See Getting started with WEM.