Setting Up PCS with 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 section tells how to install, configure, and start using Privilege Control for Servers (PCS) with the Platform Agent.

For information about the other type of agent, Privilege Control Agent, see Privilege Control Agent.

For an overview of PCS and its components, see Privilege Control for Servers with Platform Agent.

Prerequisites to Platform Agent Installation

Before you start installing and using the Platform Agent and PCS, you must already have the Verify Privileged Identity Platform set up for fundamental tasks.

Follow these procedures and understand these concepts:

• Quick Start Guide

• Identity Providers

• Authentication Profiles

• Vaulting Secrets on the Verify Privileged Identity Platform (including how to place an account in the Verify Privilege Vault vault)

If you want Active Directory support:

• Discovery for Active Directory users and servers

• Installing the IBM Security AD Connector

To be sure your tenant has the ability to use the Platform Agent, select Settings > Connection points > Agents. The Agents menu item is shown only if the feature is enabled.

PCS with Platform Agent Installation Overview

When you are ready to set up Privilege Control for Servers to work on the Verify Privileged Identity Platform and start using it with the Platform Agent, perform the following tasks.

First, ensure platform tenant prerequisites are met; see Prerequisites to Platform Agent Installation.

Then:

Task 1: Configure Firewall Ports

Task 2: Set Up Identity Provider

Task 3: Install the Platform Agent

Task 4: Set Up Authentication Profiles for PCS

Task 5: Set Up Policies

Task 6: Set Up PRA

Task 7: Set Up Use My Account

Task 1: Configure Firewall Ports

To use Privilege Control for Servers, be sure your firewall ports are configured appropriately. Use the procedure in Customer Firewall Requirements.

Task 2: Set Up Identity Provider

The Platform Agent enables identities from any identity provider to authenticate to endpoints based on policy. To target your identities, they must be integrated into the Verify Privileged Identity Platform from your external provider. Use the procedures for your desired identity type(s). See Identity Providers.

Task 3: Install the Platform Agent

Now that you have set up the platform, install the Platform Agent on your servers.

Requirements for Platform Agent Installation

Before you begin installing and setting up the Platform Agent:

• Make sure the servers where the Platform Agent will be installed are using one of the supported operating systems. See Platform Agent Supported Operating Systems and System Requirements.

• Before running the procedures in this section, we recommend you see the additional content at Managing Agents (Platform Agent). Pay particular attention to Antivirus, EDR, and Endpoint Security Exclusions.

• The Platform Agent cannot currently be installed on machines that are already running the Platform Engine. For information about the Platform Engine, see Verify Privileged Identity Platform Engine Management.

Checking for Platform Agent Installation

To see whether the Platform Agent is already installed on a given computer, view the computer's information in the Inventory page. See Inventory.

If the Platform Agent is installed, the Client Version field shows a software version number starting with 1. You can skip the next few procedures for downloading and installing the agent, because the agent is already present. Go ahead to Task 4: Set Up Authentication Profiles for PCS.

Installation Prechecks

Before the Platform Agent installs, it runs a set of prechecks on the target machine to confirm the machine is ready. In this way, any issues can be found and fixed more quickly.

If a precheck fails, the installation stops automatically and tells you what went wrong. The machine is never left in a half-installed state.

Precheck	Confirms
Supported operating system	The OS and version are on IBM Security’s supported list
Valid hostname	The machine has a valid, resolvable name so it appears correctly in the platform
Sufficient disk space	At least 500 MB free where the agent will be installed, with room for logs and updates
No conflicting agent	A Privilege Control / Verify Privilege Server Suite agent is not already installed
File and folder access	The installer can write to the locations it needs
Software signature	The agent files are genuine, signed IBM Securitysoftware
Perl installed	(Linux only) Perl is present, which some workloads require
Login prerequisites	The OS sign-in components are ready, such as credential provider and PAM module

When installing interactively with a script, each precheck prints a line to the screen. When agent installation is complete, the agent installer returns a numeric exit code. This code is provided mainly for automated tools, such as device management systems. If more than one precheck failed, the exit codes are added together into one number. In this case, the per-line messages in the table above are the easiest way to troubleshoot.

Overriding a Failed Precheck

Use with caution.

Prechecks exist to prevent broken agent installations. Overriding a failure can leave the agent in a non-working state. Do this only if IBM Security Support advises it or if you fully understand the specific failure and accept the risk.

By default, the Platform Agent will not install if a precheck fails. To force it to continue, edit the install script.

Proxy Setup

The Platform Agent supports funneling agent traffic through known egress points instead of large amounts of unique endpoint IPs. This simplifies firewall rules and ensures connectivity in restricted networks where endpoints have no direct internet access.

Authenticated proxies (requiring username and password) and auto-config scripts/PAC files are not supported.

To accomplish this, the Platform Agent is designed to respect proxy settings. To configure proxy settings:

1. In your Verify Privileged Identity Platform tenant, open the Sites page. (Use the Search bar to find it.)

2. Select a site.

3. Click Settings.

4. In the Proxy section, click Edit.

5. Enter the proxy address and port.

6. (Optional) To enable the override of an existing local proxy, select the Override local proxy checkbox.

   If this setting is not enabled, the proxy configuration will still apply if no local proxy has been set.

7. Click Save.

When you install new engines and agents in this site, they will automatically be deployed with the specified proxy setting. The existing engines and agents in the site will receive the proxy update, but they will not route traffic through the updated proxy until the next time the system and services are restarted.

Downloading the Platform Agent

To download the agent software:

1. Log in to your Verify Privileged Identity Platform tenant.

2. From the left navigation, select Settings, then Agents.

3. Click Deploy agents.

4. Select a registration code, you can either create a new one by inputting a Name, Registration maximum, and Expiration date and time; or select the Copy from existing option to re-use an existing one. Registration codes should be treated as a confidential credential.

5. Select a site or create a new one.

6. Select a Channel update setting. This setting determines the frequency of automatic updates from IBM Security.

   • Stable is typically recommended for production environments.

   • Rapid provides early access to new features.

7. Select the operating system.

8. Select the deployment method:

   • Windows MSI package: Download the generated package and copy the generated command.

   • Windows PowerShell script: Copy the generated script.

   • Linux RPM package: Download the generated package and copy the generated command. Recommended for RHEL, Rocky/Alma, Amazon Linux, or Fedora.

   • Linux DEB package: Download the generated package and copy the generated command. Recommended for Ubuntu or Debian.

   • Linux Shell script: Copy the generated script.

Installing the Linux Platform Agent

To install the Platform Agent on a server that is running a Linux operating system, use the steps in this section.

To get more details about the Linux agent, see Managing Agents (Platform Agent).

RPM or DEB package (manual)

1. Copy the entire bundle to the target machine. Keep install.sh, install.conf, and the .rpm or .deb together in one directory.

2. Create the wrapper executable if needed:
   chmod +x install.sh

3. (Recommended) Run the pre-checks:
   sudo ./install.sh --diagnose

4. Run in the installation:
   sudo ./install.sh

5. Verify:
   systemctl status delinea-engine
   Expected output: 
   active (running).
   Also perform the checks at Confirm Successful Agent Installation.

RPM or DEB package (unattended)

In these steps, as an example, it is assumed you are using Ansible.

1. Encrypt and store the bundle in your playbook repo with Ansible Vault:

   ansible-vault encrypt

   Never commit install.conf in cleartext.

2. Define your inventory, group the target hosts, splitting RPM-family and DEB-family hosts if you are shipping both bundles.

3. Write the playbook with become: true and a “skip if already installed” guard so re-runs are safe:

   1. stat the delinea-engine.service unit.

   2. Copy the bundle to /tmp/dpa-bundle.

   3. Command: ./install.sh (chdir into the bundle; gated shen: not <service>.stat.exists).

   4. systemd verify.

   5. file: state=absent cleanup

      Use the command/shell module to run install.sh, not the apt / dnf package module. The wrapper does the precheck, config placement, and enrollment.

4. (Recommended) Dry run on a canary to confirm the precheck passes before rollout. Run the playbook with --limit canary-host. Optionally, do a --diagnose only pre-flight play first.

5. Run the playbook against the group:

   ansible-playbook install-dpa.yml –ask-vault-pass

6. Verify on a sample of hosts:

   systemctl status delinea-engine

   Expected output:

   active (running)

   Also perform the checks at Confirm Successful Agent Installation.

Shell script

1. Confirm curl is present via curl --version

2. Confirm /tmp is not noexec via mount | grep ‘ /tmp ‘

3. If it is, use the RPM/DEB package or remount /tmp exec temporarily

4. Paste the copied script into a terminal on the target and run it, you may be prompted for your sudo password

5. The installation prechecks will run now, to proceed past a pre-check failure you understand, edit the copied command to set force_install=1 near the start and re-run

6. Verify:
   systemctl status delinea-engine
   Expected output: 
   active (running).
   Also perform the checks at Confirm Successful Agent Installation.

Installing the Windows Platform Agent

To install the Platform Agent on an endpoint that is running the Windows operating system, use the steps in this section.

For more details about the Windows agent, see Managing Agents.

MSI package (manual)

1. Copy the .msi file to the target machine.

2. Using an elevated command window, navigate to the folder where the .msi is stored.

3. Paste and run the copied command.

4. The installation prechecks run. If a pre-check failure occurs and you understand the failure and are not concerned about it, append FORCEINSTALL=1 to the copied command and run it again.

5. Verify service Delinea.Engine shows Running. Also perform the checks at Confirm Successful Agent Installation.

MSI package (unattended)

In these steps, as an example, the use of Microsoft Intune is assumed.

1. Package the .msi as a Windows app (Win32) (preferred) or a LOB MSI app.

2. Set the install command to the copied command. Ensure it has /qn to allow for a silent installation.

3. Set install context = System, architecture = x64.

4. Set Detection rule = MSI product code, or the Delinea.Engine service.

5. Assign to your target device group and deploy.

6. The installation prechecks run. If a pre-check failure occurs and you understand the failure and are not concerned about it, append FORCEINSTALL=1 to the command in your deployment tool and run it again.

   Use FORCEINSTALL sparingly and with caution. A precheck that fails fleet-wide usually signals a real environment issue, leaving you with agents that install but are not functional.

7. Verify your deployment tool reports exit 0; spot check service Delinea.Engine shows Running; machines should be visible in the Delinea Platform under Settings > Agent Management

Also perform the checks at Confirm Successful Agent Installation.

PowerShell script

1. Open an elevated PowerShell window (Run as administrator).

2. Confirm FullLanguage before running: $ExecutionContext.SessionState.LanguageMode #

   Expected output: FullLanguage

3. If ConstrainedLanguage is returned, stop and adjust the FullLanguage settings.

4. Run the script by pasting it directly into the elevated console.

   If you instead save it as a .ps1 file, launch it with PowerShell.exe.

5. The installation prechecks run. If a pre-check failure occurs and you understand the failure and are not concerned about it, set $ForceInstall = $true at the top of the script and run it again.

6. Verify service Delinea.Engine shows Running. Also perform the checks at Confirm Successful Agent Installation.

Confirm Successful Agent Installation

Installation of the Platform Agent is complete. To be sure the procedure was successful, confirm the agent is visible in the platform.

1. The machine should be visible in the Verify Privileged Identity Platform under Settings > Agent Management.

2. To be sure all your machines were added, check the Inventory. Follow the steps at Computer Assets.

Agent Installer Exit Code Reference

The following table shows the status codes that the agent installer can return when it is finished running.

Code	Meaning	Solution
0	Success	None required; installation proceeds normally.
-1	File or folder access denied	Run the installer with administrator (Windows) or root (Linux) privileges.
-9	Software signature verification failed	Download the installer package again; this can be caused by a corrupted installer package.
-11	Conflicting agent installed	Remove the existing Privilege Control / Verify Privilege Server Suite agent or choose a different machine.
-37	Operating system not supported	Check the supported operating systems list. See Supported Operating Systems for Agents.
-39	Hostname is invalid	Set a valid machine hostname and try again.
-41	DNS resolution failed	Verify the machine’s DNS settings; test with nslookup (Windows) or dig (Linux).
-43	Not enough disk space	Free up space (500MB is required) and run the installer again.
-197	Messaging broker port not reachable	Confirm outbound network access to the platform.
-199	Firewall is blocking traffic	Allow the required outbound connections through the firewall.
-211	TLS certificate missing or untrusted	Ensure the required root certificate is trusted on the machine.
-809	(Linux) Perl is not installed	Install Perl using your package manager.
-1621	A workload prerequisite is missing	Read the on-screen message for the specific item.
-999	Unexpected error	Try running the installer again. If the issue persists, contact IBM Security Support with the log.

Agent Installation Log Files

If you need to investigate an installation issue or failure, you will need to find the log files.

Type of Log	Windows	Linux
On-screen output	Powershell window	Terminal
Installer log files	Windows Event Log > Application log > MsiInstaller source, then search for IBM Security	/var/log/delinea-agent-install.log

Task 4: Set Up Authentication Profiles for PCS

Authentication profiles are required for multi-factor authentication (MFA) to function. An authentication profile specifies the authentication challenges required to log in to the platform and the length of time that must elapse before a user is prompted for authentication again.

To set up authentication profiles for PCS with the Platform Agent:

Follow the concepts and steps in Authentication Profiles. Follow these guidelines:

• Unlike unlike the Privilege Control Agent, the Platform Agent does not enforce password authentication on non-domain-joined machines without it being set as a Challenge in the authentication profiles. If password authentication is desired on these systems, one of your challenges in authentication profiles should be set to Password / SSO. This setting on non-domain-joined machines instantiates a Device Code Flow to present the user with a native single-sign-on experience.

• Emergency Access Profiles: You do not need to create any profiles for Emergency Access policies, because their Rule Type is always Allow.

Task 5: Set Up Policies

Policies provide users with machine-level (server) permissions for logging in to remote computers and servers managed by Verify Privileged Identity Platform and performing actions on them. By assigning machine-level policies, you can ensure that each asset adheres to compliance standards, maintaining both security and efficiency across your network.

Follow the steps in Setting Up Policies (Platform Agent).

Task 6: Set Up PRA

Privileged Remote Access (PRA) provides seamless access to remote machines through RDP (Remote Desktop Protocol) and SSH (Secure Socket Shell) without the need for a VPN (Virtual Private Network).

PRA is delivered through an Engine workload which brokers a remote session to a target’s native RDP/SSH. It does not require Platform Agent on the target.

To use PRA against Platform Agent-managed targets, you still need a Platform Engine with the PRA workload running, and network line of sight from that engine to the target.

The Platform Agent disables Network-Level Authentication (NLA) on Windows operating systems. This is required so the agent can present its login and MFA credential provider for federated users. Re-enabling NLA will break Platform Agent login and PRA functionality.

For PRA setup and prerequisites, see Privileged Remote Access .

Task 7: Set Up Use My Account

You can set up Use My Account (UMA) so you can access enrolled Linux systems without an additional login step. UMA provides single sign-on to Linux systems for users who are logged in to the Verify Privileged Identity Platform.

Use My Account requires a Platform Engine with the PRA workload running, and network line of sight from that engine to the target.

See Setting Up Use My Account.