Install/upgrade EPM agents on Windows

This topic describes how set administrators can install EPM agents on Windows endpoints.

You cannot use the previous agent configuration file to install this version. Make sure you download a new installation kit from the Download Center and use the new agent configuration file and installation key for this version.

Watch the videoCopy bookmark

Wistia video thumbnail

Do not save the text file as it leaves a local footprint. Instead, use a temporary text editor space to compose the command line, then execute the command and delete the temporary space.

Before you beginCopy bookmark

  • If agent self-defense is enforced, generate a unique secure token to use for upgrade. For information about creating this token, see Generate a secure token.

  • To enable downloading an installation kit with immediate enforcement, turn on Downloading immediately enforcement agent in the Set Configuration page.

Download the installation kit for Windows agentsCopy bookmark

  1. In the EPM management console, go to the Download Center:

    • In data centers that support the new endpoint management service, go to Endpoints (Beta) > Download Center > Windows.

    • In data centers that still support the legacy endpoint management service, go to My Computers > Download Center > Windows.

    For details about data centers that support the new endpoint management service, see Enhanced endpoint management support.

  2. You can download the latest version or one of the two previous versions of the EPM agent. Select the Windows agent to download, then click Download, or Immediate enforcement download. For details on immediate enforcement, see Agent installation methods.

  3. After the agent installation kit has been downloaded successfully, the Agent installation key window displays details about the installation kit and an installation key. This key is generated automatically by the system and cannot be retrieved later.

  4. Copy this key and save it in a separate file for use during installation, then close this window.

     

    If you cannot provide this key during installation, you have to download the agent installation kit again and get a new key.

  5. The agent installation kit is downloaded as a zip package. Unzip and extract the installation files:

    • Configuration file

    • Installation key

Install EPM agents on Windows endpointsCopy bookmark

This section describes how to install the EPM agent on Windows endpoint computers. You can choose from the following options, depending on your workflows.

Method

Description

Manual

Installs the EPM agent for Windows with an interactive wizard.

Manual with immediate enforcement

Installs the EPM agent on Windows with an interactive wizard and immediately enforces predefined policies.

Software distribution system

Installs the EPM agent with Group Policy Software Distribution or any third party distribution tool.

CLI with a configuration file

Installs the EPM agent for Windows with a CLI command, using the configuration file you downloaded.

For multiple automatic installations, make sure the file is in a shared location that can be accessed by all endpoint computers during installation.

CLI with configuration details

Installs the EPM agent for Windows with a CLI command that includes configuration details.

Click a tab to view the relevant installation procedure.

You can manually install EPM agents in either of the following ways:

Method

Description

Manually customize and apply policies

Install the EPM agent for Windows with an interactive wizard and then customize and apply policies.

Immediately enforce predefined policies

Install the EPM agent on Windows with an interactive wizard and immediately enforce predefined policies.

  1. To enable this download, go to Configuration > Set configuration > Endpoints, and turn on Download immediate enforcement agent.

  2. In the Download Center, click Immediate enforcement download.

To install an EPM agent with a wizard

  1. On the Windows endpoint, run the MSI installation file to start the agent installation wizard.

  2. When you are prompted for the installation key and configuration file, do the following:

    • Paste the installation key you received when you downloaded the installation package. The key is hidden and you cannot show its contents.

    • Browse to the folder where you unzipped the EPM installation package, and select CyberArkEPMAgentSetupWindows.config.

       

      On platforms that do not support full path navigation, like SCCM and Intune, make sure that the configuration file is in the working directory (MSI directory) and specify only the name of the configuration file without the path.

  3. Click Next to continue installation, then click Finish to exit the wizard.

After the EPM agent has been installed successfully, the EPM agent icon appears in your system tray.

For details about configuring a proxy server to integrate with the EPM service, see the knowledge base article Configure a proxy server.

To comply with corporate software distribution procedures, you can install the EPM agent with Group Policy Software Distribution or any third-party software distribution tool used by your organization, such as SCCM (System Center Configuration Manager), Marimba, LanDesk, McAfee ePolicy Orchestrator (ePO), GPO, Altiris, or Intune.

To download the installation files

  • Download the relevant MSI installation file and copy it to a shared network.

To install EPM agents for Windows using a group policy

  1. Configure a shared folder with the following user permissions:

    User

    Permissions

    Everyone

    Read

    Authenticated Users

    Read

    System

    Full control

    Administrators

    Full control

  2. Validate the newly granted permissions, by opening the shared folder from a computer with a standard user account. Verify that you can access and launch the MSI file.

  3. Open the Windows Group Policy Management console, either:

    • From the Start menu. Select Control Panel> Administrative Tools>Group Policy Management

    Or

    • On your keyboard. Press the Windows logo key + R to open the Run dialog box. Type gpmc.msc in the text box, then click OK or press Enter.

  4. If agent self-defense is active, bypass agent protection as detailed in Protect agents.

  5. Continue the deployment process with the group policy to remotely install the agent.
    For details, see the CLI with a configuration file or CLI with configuration details tab.

You can install the CyberArk EPM agent from a command line using the CyberArkEPMInstaller command line script.

To install an EPM agent using a configuration file

Run the EPM agent installation command, and specify the name of the configuration file. The installation process prompts you for any details that are not included in the command.

  
MsiExec.exe /i "<Agent msi file>" SECURE_TOKEN="<token>" INSTALLATIONKEY="key" CONFIGURATION="<configuration file>" ISDEPLOYMENT="<String>" /qn
  
MsiExec.exe /i "c:\temp\inst\vfagentsetupx64.msi" SECURE_TOKEN="D6934EF77CE1877" INSTALLATIONKEY="KCjcoKTVFrjfsnDLO" CONFIGURATION="c:\temp\inst\CyberArkEPMAgentSetupWindows.config" ISDEPLOYMENT="Yes" /qn

The following table lists the options used in the CyberArkEPMInstaller command. For examples of how these options are used, see the examples below the table.

Mandatory options

Option

Description

{path_of_the_msi_installation_file}

The full pathname or relative path of the MSI installation file that you downloaded as part of the agent installation kit.

This value depends on the current working directory. To use the relative path, make sure that the working directory is the same as the installation directory, where the MSI and config files are located.

SECURE_TOKEN

The secure token that is required to upgrade, reinstall, or uninstall the EPM when agent self-defence is activated in the agent configuration.

 

The first time you install the EPM agent on Windows, this option is not required.

INSTALLATIONKEY

The installation key you received when you downloaded the agent installation kit.

CONFIGURATION

The full pathname or relative path of the agent installation configuration file that you downloaded as part of the agent installation kit.

This value depends on the current working directory. To use the relative path, make sure that the working directory is the same as the installation directory, where the MSI and config files are located.

ISDEPLOYMENT

Deploys the EPM agent. Set this value to Yes.

Only use this parameter when you install the EPM agent with Microsoft Intune.

IOT_CERTIFICATE_ID

A unique identifier for the certificate. It is used to authenticate the device and ensure that it is recognized by the platform.

IOT_PRIVATE_KEY

The private key associated with the certificate. The private key is used to securely sign communications between the device and the platform, ensuring data integrity and authenticity.

IOT_CERTIFICATE

The actual certificate, which includes the public key and other identifying information. The certificate is used to establish a secure connection between the device and the platform.

IOT_ENDPOINT

The endpoint URL of the platform. It is the address to which the device sends its data and from which it receives commands.

IOT_ENV

Defines the environment in which the device is operating, such as development, testing, or production. It helps to ensure that the device connects to the correct instance of the platform.

Option for silent installation

Option

Description

/qn

Installs the EPM agent in silent mode.

Non-mandatory options

Option

Description

PROXYSERVER

The name or IP address of the proxy server that is enabled for the EPM agent during installation.

The address for PROXYSERVER should not include http or https.

Correct:PROXYSERVER=my-proxy.mycompany.com

Incorrect:PROXYSERVER=https://my-proxy.mycompany.com

PROXYPORT

The port used for communication between the proxy server and the EPM agent.

PROXYUSER

The name of the user that connects to the proxy server for the EPM agent.

PROXYPASSWORD

The password of the proxy user.

PROXYPAC

The path of the proxy auto configuration file that you can use to configure the proxy.

REINSTALLMODE

Required to run the installation process in reinstall mode.

Set this option to REINSTALLMODE=vm.

/log

Generates a log file of the installation. Specify the full path of the log file.
Examples

The following commands show examples of different installation scenarios.

First time EPM agent installation

  
MsiExec.exe /i "<Agent msi file>" INSTALLATIONKEY="key" CONFIGURATION="<configuration file>" /qn
  
MsiExec.exe /i "c:\temp\inst\vfagentsetupx64.msi" INSTALLATIONKEY="KCjcoKTVFrjfsnDLO" CONFIGURATION="c:\temp\inst\CyberArkEPMAgentSetupWindows.config" /qn

Generate a log during installation

  
MsiExec.exe /i "<Agent msi file>" INSTALLATIONKEY="key" CONFIGURATION="<configuration file>" /log "<log>" /qn
  
MsiExec.exe /i "c:\temp\inst\vfagentsetupx64.msi" INSTALLATIONKEY="KCjcoKTVFrjfsnDLO" CONFIGURATION="c:\temp\inst\CyberArkEPMAgentSetupWindows.config" /qn

Enable proxy support during installation

For details about configuring a proxy server to integrate with the EPM service, see the knowledge base article Configure a proxy server.

Enable proxy support for an EPM agent as part of MSI installation when proxy authentication is required

  
MsiExec.exe /i "<Agent msi file>" INSTALLATIONKEY="key" CONFIGURATION="<configuration file>"  PROXYSERVER="<server name>" PROXYPORT="<proxy port>" PROXYUSER="<user name>" PROXYPASSWORD="<password>" /qn
  
MsiExec.exe /i "c:\temp\inst\vfagentsetupx64.msi" INSTALLATIONKEY="KCjcoKTVFrjfsnDLO" CONFIGURATION="c:\temp\inst\CyberArkEPMAgentSetupWindows.config" PROXYSERVER="10.10.50.1" PROXYPORT="8080" PROXYUSER="proxyadmin" PROXYPASSWORD="abc123" /qn

Reinstall an EPM Windows agent

  
MsiExec.exe /i "<Agent msi file>" SECURE_TOKEN="<token>" INSTALLATIONKEY="key" CONFIGURATION="<configuration file>" REINSTALLMODE=vm /qn
  
MsiExec.exe /i "c:\temp\inst\vfagentsetupx64.msi" SECURE_TOKEN="D6934EF77CE1877" INSTALLATIONKEY="KCjcoKTVFrjfsnDLO" CONFIGURATION="c:\temp\inst\CyberArkEPMAgentSetupWindows.config" REINSTALLMODE=vm /qn

You can install the CyberArk EPM agent from a command line, and specify the configuration details as part of the command instead of a configuration file.

Using a configuration file, instead of including all configuration details in the command line, is simpler and less prone to error.

To install an EPM agent using configuration details

You can use a configuration file, instead of including all configuration details in the command line. Using a configuration file is simpler and less prone to error.

Run the EPM agent installation command, and specify the details of the configuration file required for your deployment. The installation process prompts you for any details that are not included in the command.

  
MsiExec.exe /i "<Agent msi file>" 
SECURE_TOKEN="<token>" 
INSTALLATIONKEY="<key>"
ISDEPLOYMENT="<String>" 
DISPATCHER_URL="<URL of the EPM server>"
SET_NAME="<Set name>"
REGISTER_TOKEN="<Registration token>"
SET_ID="<Unique Set ID>"
CONFIG_VERSION="<Config file version>"
IV="<Internal IV code>"
SET_KEY ="Key"
SIG="<Signature of the above combined values>" /qn
  
MsiExec.exe /i "c:\temp\inst\vfagentsetupx64.msi" 
SECURE_TOKEN="D6934EF77CE1877" 
INSTALLATIONKEY="KCjcoKTVFrjfsnDLO"
ISDEPLOYMENT="Yes" 
DISPATCHER_URL="https://MyCompany.EPM.com/VfAgent.asmx"
SET_NAME="Set1"
REGISTER_TOKEN="V7dWmPJUdv730LF"
SET_ID="UunD512O7Nfvs"
CONFIG_VERSION="1"
IV="gvD8jenJTJumd39"
SET_KEY ="CmkTXT45bkHL+Xv065oDWc"
SIG="PFSju820nGnwQx82In" /qn

The following table lists the options used in the command. For examples of how these options are used, see the examples below the table.

Mandatory options

Option

Description

{path_of_the_msi_installation_file}

The full pathname or relative path of the MSI installation file that you downloaded as part of the agent installation kit.

This value depends on the current working directory. To use the relative path, make sure that the working directory is the same as the installation directory, where the MSI and config files are located.

SECURE_TOKEN

The secure token that is required to upgrade, reinstall, or uninstall the EPM when agent self-defence is activated in the agent configuration.

 

The first time you install the EPM agent on Windows, this option is not required.

INSTALLATIONKEY

The installation key you received when you downloaded the agent installation kit.

ISDEPLOYMENT

Deploys the EPM agent. Set this value to Yes.

Only use this parameter when you install the EPM agent with Microsoft Intune.

DISPATCHER_URL

The URL of the EPM server.

SET_NAME

The name of the set.

REGISTER_TOKEN

A unique registration token for this agent installation.

SET_ID

The unique ID of the set.

CONFIG_VERSION

The configuration file version.

IV

An internal signature.

SET_KEY

A security key for the set.

SIG

A signature of the combined values specified in this command, to prevent tampering.

IOT_CERTIFICATE_ID

A unique identifier for the certificate. It is used to authenticate the device and ensure that it is recognized by the platform.

IOT_PRIVATE_KEY

The private key associated with the certificate. The private key is used to securely sign communications between the device and the platform, ensuring data integrity and authenticity.

IOT_CERTIFICATE

The actual certificate, which includes the public key and other identifying information. The certificate is used to establish a secure connection between the device and the platform.

IOT_ENDPOINT

The endpoint URL of the platform. It is the address to which the device sends its data and from which it receives commands.

IOT_ENV

Defines the environment in which the device is operating, such as development, testing, or production. It helps to ensure that the device connects to the correct instance of the platform.

Option for silent installation

Option

Description

/qn

Installs the EPM agent in silent mode.

If this parameter is not included, installation automatically starts in interactive mode.

Non-mandatory options

Option

Description

PROXYSERVER

The name or IP address of the proxy server that is enabled for the EPM agent during installation.

The address for PROXYSERVER should not include http or https.

Correct:PROXYSERVER=my-proxy.mycompany.com

Incorrect:PROXYSERVER=https://my-proxy.mycompany.com

PROXYPORT

The port used for communication between the proxy server and the EPM agent.

PROXYUSER

The name of the user that connects to the proxy server for the EPM agent.

PROXYPASSWORD

The password of the proxy user.

PROXYPAC

The path of the proxy auto configuration file that you can use to configure the proxy.

REINSTALLMODE

Required to run the installation process in reinstall mode.

Set this option to REINSTALLMODE=vm.

/log

Generates a log file of the installation. Specify the full path of the log file.

NEEDREBOOTPROMPT

Whether a reboot prompt is displayed after upgrade is finished, before the EPM agent machine is restarted.

Set this option to NEEDREBOOTPROMPT=0.
Examples

The following commands show examples of different installation scenarios.

First time EPM agent installation

  
MsiExec.exe /i "<Agent msi file>" 
INSTALLATIONKEY="key"
DISPATCHER_URL="<URL of the EPM server>"
SET_NAME="<Set name>"
REGISTER_TOKEN="<Registration token>"
SET_ID="<Unique Set ID>"
CONFIG_VERSION="<Config file version>"
IV="<Internal IV code>"
SET_KEY ="Key"
SIG="<Signature of the above combined values>" /qn
  
MsiExec.exe /i "c:\temp\inst\vfagentsetupx64.msi" 
INSTALLATIONKEY="KCjcoKTVFrjfsnDLO"
DISPATCHER_URL="https://MyCompany.EPM.com/VfAgent.asmx"
SET_NAME="Set1"
REGISTER_TOKEN="V7dWmPJUdv730LF"
SET_ID="UunD512O7Nfvs"
CONFIG_VERSION="1"
IV="gvD8jenJTJumd39"
SET_KEY ="CmkTXT45bkHL+Xv065oDWc"
SIG="PFSju820nGnwQx82In" /qn

Generate a log during installation

EPM can generate a log file during installation, so that you can review the process. In the command, specify the full pathname of the log file to create.

  
MsiExec.exe /i "<Agent msi file>" 
INSTALLATIONKEY="key"
DISPATCHER_URL="<URL of the EPM server>"
SET_NAME="<Set name>"
REGISTER_TOKEN="<Registration token>"
SET_ID="<Unique Set ID>"
CONFIG_VERSION="<Config file version>"
IV="<Internal IV code>"
SET_KEY ="Key"
SIG="<Signature of the above combined values>" 
/lof "<filename>" /qn
  
MsiExec.exe /i "c:\temp\inst\vfagentsetupx64.msi" 
INSTALLATIONKEY="KCjcoKTVFrjfsnDLO"
DISPATCHER_URL="https://MyCompany.EPM.com/VfAgent.asmx"
SET_NAME="Set1"
REGISTER_TOKEN="V7dWmPJUdv730LF"
SET_ID="UunD512O7Nfvs"
CONFIG_VERSION="1"
IV="gvD8jenJTJumd39"
SET_KEY ="CmkTXT45bkHL+Xv065oDWc"
SIG="PFSju820nGnwQx82In"
/log "c:\temp\inst\install.log" /qn

Enable proxy support during installation

Enable proxy support for an EPM agent as part of MSI installation when proxy authentication is required.

For details about configuring a proxy server to integrate with the EPM service, see the knowledge base article Configure a proxy server.

  
MsiExec.exe /i "<Agent msi file>" 
INSTALLATIONKEY="key"
DISPATCHER_URL="<URL of the EPM server>"
SET_NAME="<Set name>"
REGISTER_TOKEN="<Registration token>"
SET_ID="<Unique Set ID>"
CONFIG_VERSION="<Config file version>"
IV="<Internal IV code>"
SET_KEY ="Key"
SIG="<Signature of the above combined values>" 
PROXYSERVER="<server name>" 
PROXYPORT="<proxy port>" 
PROXYUSER="<user name>" 
PROXYPASSWORD="<password>" /qn
  
MsiExec.exe /i "c:\temp\inst\vfagentsetupx64.msi" 
INSTALLATIONKEY="KCjcoKTVFrjfsnDLO"
DISPATCHER_URL="https://MyCompany.EPM.com/VfAgent.asmx"
SET_NAME="Set1"
REGISTER_TOKEN="V7dWmPJUdv730LF"
SET_ID="UunD512O7Nfvs"
CONFIG_VERSION="1"
IV="gvD8jenJTJumd39"
SET_KEY ="CmkTXT45bkHL+Xv065oDWc"
SIG="PFSju820nGnwQx82In"
PROXYSERVER="10.10.50.1" 
PROXYPORT="8080" 
PROXYUSER="proxyadmin" 
PROXYPASSWORD="abc123" /qn

Reinstall an EPM Windows agent

  
MsiExec.exe /i "<Agent msi file>" 
SECURE_TOKEN="<token>" 
INSTALLATIONKEY="key"
DISPATCHER_URL="<URL of the EPM server>"
SET_NAME="<Set name>"
REGISTER_TOKEN="<Registration token>"
SET_ID="<Unique Set ID>"
CONFIG_VERSION="<Config file version>"
IV="<Internal IV code>"
SET_KEY ="Key"
SIG="<Signature of the above combined values>" 
REINSTALLMODE=vm /qn
  
MsiExec.exe /i "c:\temp\inst\vfagentsetupx64.msi" 
SECURE_TOKEN="D6934EF77CE1877" 
INSTALLATIONKEY="KCjcoKTVFrjfsnDLO"
DISPATCHER_URL="https://MyCompany.EPM.com/VfAgent.asmx"
SET_NAME="Set1"
REGISTER_TOKEN="V7dWmPJUdv730LF"
SET_ID="UunD512O7Nfvs"
CONFIG_VERSION="1"
IV="gvD8jenJTJumd39"
SET_KEY ="CmkTXT45bkHL+Xv065oDWc"
SIG="PFSju820nGnwQx82In"
REINSTALLMODE=vm /qn

Upgrade EPM agents on Windows endpointsCopy bookmark

This section describes how to upgrade the EPM agent on Windows endpoint computers. You can choose from the following options.

Method

Description

EPM management console

Upgrades the EPM agent for Windows with an interactive wizard.

  • The procedure for deployments in data centers that support the new endpoint management service is in the Endpoints (Beta) page tab.

  • The procedure for deployments in data centers that still support the legacy endpoint management service is in the My Computers page tab.

For a list of data centers that support the new endpoint management service, see Enhanced endpoint management support.

Immediate enforcement

Upgrades the EPM agent on Windows with an interactive wizard and immediately enforces predefined policies.

Click a tab to view the relevant installation procedure.

Upgrade the agent on a single endpoint

  1. In the row of the selected endpoint, click the More actions (...) icon and select Upgrade agent.

  2. In the Upgrade agents window, select the agent version to install and then click Upgrade.

  3. Click Upgrade again to confirm that you want to upgrade the EPM agent on the selected endpoint.

Upgrade the agent on multiple endpoints

  1. Select multiple endpoints, then click Upgrade.

  2. For each agent, select the agent version to install on each operating system, then click Upgrade.

  3. Click Upgrade again to confirm that you want to upgrade the EPM agent on all selected endpoints.

Upgrade all agents in the set

  1. In the Endpoints (Beta) page, click Upgrade all agents.

  2. For each platform, select the agent version to install, then click Upgrade.

  3. Click Upgrade again to confirm that you want to upgrade all EPM agents in the set.

For more details, see Upgrade agents.

On the My Computers page, you can group and filter the computers in your set on which agents are installed.

  • When you initiate agent upgrade from the EPM management console, only endpoints that are connected to the network are upgraded. You can connect endpoints within 6 hours after you start this upgrade, after which you have to initiate upgrade again.

  • You can upgrade a maximum of 500 agents simultaneously from the EPM management console.

  1. Select Computer > Check Agents with Older Version to select the endpoints whose agents are not upgraded.

    Select up to 500 endpoints.

  2. Select Action > Upgrade Checked to upgrade the selected computers.

  3. To stop the upgrade process, select Action > Cancel Upgrade.

You can upgrade the EPM agent on Windows endpoints and immediately enforce predefined policies.

  1. In the Download Center, download the agent installation kit for Immediate Enforcement.

  2. Uninstall the immediate enforcement agent from the endpoint machine.

  3. Install the EPM agent as described above in Install EPM agents on Windows endpoints.

 

Add the EPM agent to a standard or golden image