Managing Agents (Platform Agent)

This feature is currently available only to customers participating in a Private Preview. If you'd like to participate and be among the first to try this feature, ask our support or account team for details.

This page gives information relevant to the Platform Agent. For information about the other type of agent, Privilege Control Agent, see Privilege Control Agent.

This page gives information you might need to know in the course of managing the Platform Agent installed as part of your Verify Privileged Identity Platform deployment.

Installing Agents on Computers to be Managed

This section describes the recommended steps for deploying Platform Agent software on your endpoints.

System Requirements

Be sure the computers where you are installing the IBM Security Platform Agent are running one of the supported operating systems. See Supported Operating Systems for Agents.

About the Deployment Process

There is no technical requirement that you only work with a subset of computers at a time, but the process of checking computers for potential problems and resolving open issues is more manageable when applied to a subset of computers. It is also more practical to migrate user populations in stages rather than all at once. After you step through the process a few times, you'll be able to anticipate and resolve potential issues more quickly and move into a more rapid deployment model.

Selecting a Target Set of Computers

As a first step in preparing to install Platform Agent software, select a target set of computers on which to deploy. The target set can be based on any criteria you choose. In many organizations, new software must always be installed in the development environment first, then in the pre-production environment, before it can be deployed in the production environment. If your organization has this type of requirement, the first target set of computers would be the computers in the development environment.

Other possible candidates for the target set might be computers that:

  • Have been identified for changes by an audit finding

  • Are in the same physical location, such as a particular data center

  • Share common attributes, such as all Red Hat Linux computers or all of the servers in a Web farm

  • Are used by a particular department, project, or line of business

  • Have a common set of users who need access to the computer resources

After you have identified a target set of computers, you are ready to begin the deployment. You should notify the user community that you are planning to install software on the target set of computers. For example, you may want to notify users by sending out an email message.

Options for Deploying Platform Agent

To deploy the Platform Agent, you can choose from the following options:

  • Run the agent installation script locally on your computer.

  • Create a configuration file and run the installation script remotely on any computer in silent mode.

  • Use the install or update operations in the native package installer for your operating environment.

  • Use a commercial or custom software distribution tool.

If you want to use one of these installation options and need more information, see Task 3: Install the Platform Agent.

Understanding Pre-Checks and Error Codes

Normally, when you run the Platform Agent installation, whether through a script or installer package, an exit code of 0 will be returned if the operation is successful. If any other code is returned, you need to troubleshoot the issue. For more information about the possible status codes that can be returned when the installer exits, see Agent Installer Exit Code Reference.

Verifying Platform Agent Status

You can verify the status of the Platform Agent from the platform UI or from the host where the agent is installed.

Verifying from Platform UI

To verify the status of the Platform Agent from the platform UI, select Settings > Agents. The display includes:

  • Status

    • Offline: The agent is not connected to the Platform

    • Online: The agent is connected to the Platform

    • Failed: A deployment terminated in failure

    • Stopped: A deployment was administratively stopped

    • Key rotation pending: If this status persists after 30 minutes, verify Outbound communication on port 443 is open. If it is, see Collecting Debugging Information and escalate to IBM Security Support.

  • Utilization Status of the agent

    • Unutilized: The agent is installed, but not a subject of any policy

    • Utilized: The agent is a subject of at least one policy

  • Workload health per workload

    • Pending: Selected but not yet ready, installation waiting to be scheduled

    • Active: Workload is operational

    • Failed: Terminated in failure, retry is not expected. See Collecting Debugging Information and escalate to IBM Security Support.

    • Unknown: State couldn’t be obtained. If the endpoint is online and this status persists after 30 minutes, contact IBM Security Support.

  • Agent version (helpful when deciding whether to upgrade)

    Platform agent versions follow the versioning format 1_xx_xx. For example, 1.17.64. The versioning format for the Privilege Control Agent is different.

See Viewing Agent Status.

Verifying from Agent Host

On a Windows host, open Service Manager and look for the Delinea.Engine service. The status should be Running. The worker process is Delinea.EnginePool.Engine.Shell.Worker.exe. Windows Event Viewer entries tagged with the agent's source name provide additional context.

Managing Workloads

Platform Agent workloads are policy-driven. When you deploy a policy that targets a machine, the workloads needed by that policy activate automatically on the agent. When a workload is no longer targeted by any policy, the workload deactivates.

There is no per-machine workload toggle. To add or remove workloads on a specific machine, change the policies that target it.

To restart a workload for an individual machine:

  1. Select Settings > Agents.

  2. Select the machine.

  3. In the Workloads section of Overview, hover the workload name until an ellipsis appears, then select Restart workload.

To view logs for a workload for an individual machine:

  1. Select Settings > Agents.

  2. Select the machine.

  3. In the Workloads section of Overview, click View logs for the desired workload.

For details on authoring policies that target Platform Agent machines, see Setting Up Policies (Platform Agent).

Files and Directories on Platform Agent

Platform Agent and Platform Engine share the same binary framework. As a result, many installed paths use "engine" naming on a Platform Agent install. The package name is delinea-platform-agent, but the directories are named Delinea Engine (Windows) or delinea-engine (Linux). Platform Agent shares its binary framework with Platform Engine, and log paths reflect the shared framework.

Windows Files and Directories

Directory Contents

  • C:\Program Files\Delinea Engine\

  • C:\Program Files\Delinea\Platform Agent\

Binaries
C:\ProgramData\Delinea Engine\log\ Runtime / agent operational logs
/usr/sbin /usr/bin C:\ProgramData\Delinea Engine\data\runtime\ Workload runtime files
C:\ProgramData\Delinea Engine\data\settings\*.config Agent state
Windows Event Log > Application log > search “Delinea” System events
Windows Event Log > Application log > MsiInstaller source > search “Delinea” Installer logs
Powershell window On-screen output (script installation)

Linux Files and Directories

Directory Contents

/opt/delinea-engine/

 Binaries
/var/delinea-engine/data/ Data
/var/delinea-engine/log/ Runtime / agent operational logs
/var/delinea-engine/data/runtime/ Workload runtime files
/var/delinea-engine/data/settings/*.config Agent state
/var/log/delinea-agent-install.log Install log (one-time)
On-screen output (script installation) Terminal

Antivirus, EDR, and Endpoint Security Exclusions

Endpoint security products such as antivirus, EDR, host-based firewalls, DLP, and so on can interfere with Platform Agent operation. Common patterns:

  • Real-time scanners flag agent binaries as suspicious and block execution

  • Behavioral analysis quarantines processes that update files in C:\ProgramData\ or /var/

  • TLS-inspecting proxies break the agent's mutual TLS connection to platform endpoints

  • Aggressive scanning of agent log directories degrades agent performance

To prevent these issues, your endpoint security team should configure exclusions for Platform Agent paths, processes, and network endpoints. The exclusions below are recommended starting points; tune them according to your security team's risk model.

Windows Exclusions

Directory exclusions (recursive):

  • C:\Program Files\Delinea Engine\

  • C:\ProgramData\Delinea Engine\

  • C:\Program Files\Delinea\Platform Agent\

Process exclusions:

  • Delinea.EnginePool.Engine.Shell.Worker.exe (the agent worker process and all child processes)

Registry exclusions:

  • HKLM\SYSTEM\CurrentControlSet\Services\Delinea.Engine

  • HKLM\Software\Delinea\LoginAgent

  • HKLM\Softare\Delinea\EngineShell

Linux Exclusions

Directory exclusions:

  • /opt/delinea-engine/

  • /var/delinea-engine/

  • /var/delinea/

  • /etc/delinea/

  • /opt/delinea/

  • /var/log/delinea-agent-install.log

Process exclusions:

  • The delinea-engine systemd unit and its child processes

Socket file exclusions:

  • /var/run/delinea-agentcore-workload.socket

  • /var/run/delinea-login-workload.socket

  • /var/run/delinea-privilege-elevation-workload.socket

Network and Communication Exclusions

If your security stack performs TLS inspection, deep packet inspection, or hostname-based firewall enforcement, allowlist Platform Agent's outbound traffic.

Ports:

  • 443/TCP outbound (primary agent-to-platform traffic, including MQTT-over-WebSocket and gRPC)

  • 5671/TCP outbound (AMQP fallback path)

FQDNs:

Platform Agent uses the same set of regional Platform endpoints as Platform Engine. For the FQDN list, see Platform Engine URLs.

Purpose of Exclusions

The benefit of exclusions is to ensure your endpoint security stack does not interfere with the agent's normal operation while preserving the security stack's coverage of all other system activity. The exclusions are scoped to:

  • Specific directories owned by Platform Agent

  • Specific processes that constitute the agent

  • Specific outbound network endpoints required for agent operation

These exclusions do not weaken endpoint security for any other process, file, or network destination. They specifically allow Platform Agent to function while everything else continues to be protected.

Exclusion Reference Patterns

Platform Agent's exclusion structure follows established patterns from related IBM Security products. See Antivirus Exclusions in the Verify Privilege Manager documentation.

Vendor-specific configuration steps for individual antivirus or EDR products are outside the scope of this documentation. Each vendor's UI and exclusion mechanics change frequently. Your security team will translate the path/process/network lists above into their tool's exclusion configuration format.

Updating the Platform Agent

After installation, the Platform Agent keeps itself up to date automatically. Verify Privileged Identity Platform manages the agent's version centrally, downloading and applying new releases without requiring you to run installers or touch individual machines.

You control when updates are applied through each site's Update preferences. Because update preferences are set at the site level, every agent assigned to a site follows that site's schedule.

Choosing How Updates are Applied

  1. Select Settings > Sites.

  2. Open the site whose agents you want to manage.

  3. Select Settings, then Edit Engine and Agent update preferences.

  4. Choose one of the following:

    • Auto-update on release – Agents update automatically whenever a new version is released. Choose this to always stay current with the least administrative effort.

    • Schedule update – Agents update only during a weekly maintenance window that you define. Choose this when you need updates to occur outside business hours or to align with a change-management window. Use the information in Setting a Scheduled Update Window.

Setting a Scheduled Update Window

When you select Scheduled update, you can specify the following options:

  • Occurrence: the day of the week the update window opens (Monday through Sunday).

  • Time: the time the window opens, entered in your local time zone, shown near the setting.

For example, setting the occurrence to Saturday and the time to 10:00 PM applies available updates during the late-Saturday maintenance window each week. Agents check for and apply any pending update at the next scheduled window; if no update is available, nothing changes.

Saving update preferences requires permission to manage the site. If you don't have that permission, the settings are read-only.

Update preferences apply to the entire site. To give different groups of machines different update schedules, place them in separate sites.

Uninstalling the Platform Agent

When the Platform Agent is uninstalled, the endpoint is removed from the Verify Privileged Identity Platform inventory view if it has not been discovered by other discovery sources.

Uninstalling From the Platform

To uninstall the Platform Agent from the platform UI:

  1. Select Settings > Connection points > Agents.

  2. Select an agent.

  3. Click Delete agent.

  4. Click Confirm.

This will also uninstall the agent on the endpoint.

Uninstalling on Windows Endpoint

This section describes how to uninstall the Platform Agent. Several techniques are given, depending on how the agent was installed and how you would like to uninstall it.

MSI

If the Platform Agent was installed with MSI, you can uninstall it on a Windows endpoint with either an interactive technique or a command.

Interactive:

Open Settings > Apps (or Control Panel > Programs and Features) and uninstall IBM Security Platform Agent.

Command:

  1. Get the ProductCode by running this command in PowerShell as Admin:

    Get-ChildItem 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall','HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall' | Get-ItemProperty | Where-Object DisplayName -eq 'Delinea Platform Agent' | Select-Object DisplayName, DisplayVersion, PSChildName

    The PSChildName value is the ProductCode, a GUID like {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}.

  2. Uninstall using the ProductCode by running this command in Cmd as Admin:

    Msiexec.exe /x {PASTE-GUID-HERE} /qn /norestart /l*v C:\Windows\Temp\pa-uninstall.log

PowerShell

If the agent was installed via PowerShell script, execute the command below as administrator with PowerShell.

cd "C:\Program Files\Delinea Engine\scripts";.\uninstall-engine-win.ps1;

The uninstaller removes:

  • Agent binaries from C:\Program Files\Delinea Engine\

  • Agent data from C:\ProgramData\Delinea Engine\

  • The Delinea.Engine service registration

  • All Add/Remove Programs entries

Uninstalling on Linux Endpoint

In order for the uninstall to complete successfully, the uninstall command must be run from the home or root directory.

RPM

If the Platform Agent was installed from an RPM package (RHEL, Amazon Linux, or other RPM-based installs), you can uninstall it on a Linux endpoint with the following command:

```bash
sudo rpm -e delinea-platform-agent
```

DEB

If the Platform Agent was installed from a DEB package (Ubuntu, Debian, or other DEB-based installs), you can uninstall it on a Linux endpoint with the following command:

```bash
sudo dpkg --purge delinea-platform-agent
```

Shell Script

If the Platform Agent was installed from a shell script, you can uninstall it on a Linux endpoint with the following command:

```bash
sudo /opt/delinea-engine/scripts/uninstall-engine-linux.sh
```

The package's pre-uninstall and post-uninstall scripts:

  • Stop the delinea-engine systemd service

  • Remove agent binaries from /opt/delinea-engine/

  • Remove agent data from /var/delinea-engine/

  • Remove the systemd unit file