Upgrade the Privilege Cloud Connector v12.7 and later

This topic describes the Privilege Cloud Connector upgrade for versions 12.7 and later.

 

Upgrading the CPM and PSM components requires downtime (typically a few minutes). We recommend performing the upgrade at a time that will have the least impact on your operations.

Perform the following steps:

Step 1: Before you begin

For CPM upgrade, there are two upgrade tools:

  • Connector Management installer (recommended installer). Currently supports CPM upgrade for any installed CPM in your system, disregarding which installer was used at the time it was installed.

  • Privilege Cloud installer (legacy installer)

The upgrade workflows support both installer tools.

Select one of the following tools and perform the related steps:

  1. Prepare user credentials.

    • Installeruser password, as described in Set the Installeruser password.

    • Local Admin user, with full Admin rights. For In-domain deployments, this must be a domain user.

  2. Prepare the Privilege CloudConnector machine:

    #

    Step

    Action
    a Take a snapshot of the Connector machine before upgrading. Stop the server, take a snapshot, reboot the server and log in again.
    b Generate a Group Policy report of the Connector server.

    In the CMD line or PowerShell, run

    Gpresult /h C:\PolicyBeforeUpgrade.html

    c

    Check the current CPM and PSM versions

    Right-click Start menu > Application and Features

    Note the PSM and CPM versions

    d

    Check the CPM mode

    Check Services.msc > CyberArk Password Manager

    If the service is running, this is the primary CPM.

    If the service is not running, this is the DR CPM.
    e Download the latest Privilege Cloud software package

    From the CyberArk marketplace software area download:

    • Privileged Session Manager-Rls-[latest release].zip

      • Privilege Cloud Connector Unified Hardening GPO-v2.2.0.zip

      • Privilege Cloud Connector Unified Hardening GPO-v2.2.0.txt
    f Check the zip files are not blocked

    Check Properties > General, Security field.

    Or, in the folder storing the CyberArk files, run the PowerShell command:

      
    dir -r | Unblock-File

    g

    Extract the CPM and PSM zip packages

    Save the extracted files in the installation root drive, in a folder path that adheres to Windows 8.3 formatting. For example: C:\Temp\Cyberark[latest release]

    Do not run the upgrade from your user desktop due to Microsoft maximum file path length limitations.

    h

    Copy the GPO Hardening package to the domain server and extract the zip package.

    For both CPM and PSM:

    Copy the Unified GPO hardening zip package downloaded in #e above and extract it.

    Only PSM:

    Extract Privileged Session Manager zip file downloaded in #e above, copy over the CyberArk Hardening - In Domain - PSM.zip file and extract it.

  3. Disable the antivirus agent if it is installed on your server.

  4. Before upgrading the PSM:

    #

    Step

    Action

    a

    Back up these files:

    • PSM\Hardening\PSMHardening.ps1

    • PSM\Hardening\PSMConfigureAppLocker.xml

    • PSM\basic_psm.ini

    • All logs from PSM\Logs folder in previous step

    b

    For domain users PSMConnect/PSMAdminConnect:

    • Check that the local PSMConnect and PSMAdminConnect users are in the Built-in\Users group on the Connector:

      From MMC or lusrmgr.msc > Users and Groups > either view PSMConnect/PSMAdminConnect users and add to Built-in\Users group, or view Built-in\Users group and add PSMConnect/PSMAdminConnect users.

    • Apply secrets management to the PSMConnect and PSMAdminConnect users and ensure they are managed by CPM.

      CyberArk strongly recommends this step.
    c Check the PSMConfigureAppLocker.xml file, which contains tailored rules for your organization's executable files.

    • If you have an edited PSMConfigureAppLocker.xml file that contains tailored rules for your executable files, retain your current file.

    • Validate all custom changes in the customized PSMConfigureAppLocker.xml file before running the hardening script.

    During the upgrade, the AppLocker file automatically merges all custom changes you’ve applied to the configuration of your AppLocker from previous versions.

    • If you have any executable files that have been added to your environment and you want to define them in the file, do it now.

    d

    Optional:

    If PSM Health Check is installed and is a version older than v1.2, update the PSM Health Check version to the latest version.

    See Upgrade PSM Health Check.

  5. In the Connector Management tool, check for available upgrades.

    The Connector Management tool supports the following components for upgrade:

    • Management Agent

    • CPM

      1. In the connector list, check the following indicators:

        Indicator

        Description

        Component status bar

        A status bar at the top of the connector list indicates component statuses and the number of components in each group:

        • Components with errors

        • Available upgrades

        These are filter tabs, allowing to filter the component list and display the relevant components.

        Upgrade column

        The right-most column offers a quick access action link, allowing you to initiate an upgrade on the related connector.

        Click the following image to enlarge the display:

      2. Click Available upgrades to display the connectors with applicable upgrades.

      3. In a connector row, hover over the Upgrade link in the right-most column. A tooltip displays the upgradable components and the update version.

      4. Select the connector you want to upgrade and follow the steps below.

  6. For systems with PSM high availability, ensure minimal downtime by temporarily diverting traffic from the upgrading PSM.

    When diverting a platform that is defined for a specific PSM to a different PSM, any targets that are defined to connect with the specific PSM will not be accessible.

    1. In the Privilege Cloud Portal, access each Windows platform and redirect it to an alternate non-upgrading PSM ID:

      Go to Administration > Platform management and in each platform select Manage PSM connector.

    2. Select the pencil icon at the top of the window and from the list of PSMs, select a non-upgrading PSM. This directs the platform to that PSM.

      • You can also map the PSMs directly in Policies.xml

    3. Upgrade the PSM which currently should not have any mapped platforms.

    4. Repeat steps a-b and now remap the platforms to the newly upgraded PSM.

    5. Repeat this process for all other PSM servers that require upgrading.

    6. Revert to your original PSM policies.

    When diverting a platform that is defined for a specific PSM to a different PSM, any targets that are defined to connect with the specific PSM will not be accessible.

  7. Stop the following services:

    • PSM: Cyber-Ark Privileged Session Manager

    • CPM: CybeArk Password Manager

    • Scanner: CyberArk Central Policy Manager Scanner

  1. Prepare user credentials.

    • Installeruser password, as described in Set the Installeruser password.

    • Local Admin user, with full Admin rights. For In-domain deployments, this must be a domain user.

  2. Prepare the Privilege Cloud Connector machine:

    #

    Step

    Action
    a Take a snapshot of the Connector machine before upgrading. Stop the server, take a snapshot, reboot the server and log in again.
    b Generate a Group Policy report of the Connector server.

    In the CMD line or PowerShell, run

    Gpresult /h C:\PolicyBeforeUpgrade.html

    c

    Check the current CPM and PSM versions

    Right-click Start menu > Application and Features

    Note the PSM and CPM versions

    d

    Check the CPM mode

    Check Services.msc > CyberArk Password Manager

    If the service is running, this is the primary CPM.

    If the service is not running, this is the DR CPM.
    e Download the latest Privilege Cloud software package

    From the CyberArk marketplace software area download:

    • Privileged Session Manager-Rls-[latest release].zip

    • Central Policy Manager-RI[latest release].zip

    • Privilege Cloud Connector Unified Hardening GPO-v2.2.0.zip

    • Privilege Cloud Connector Unified Hardening GPO-v2.2.0.txt
    f Check the zip files are not blocked

    Check Properties > General, Security field.

    Or, in the folder storing the CyberArk files, run the PowerShell command:

      
    dir -r | Unblock-File

    g

    Extract the CPM and PSM zip packages

    Save the extracted files in the installation root drive, in a folder path that adheres to Windows 8.3 formatting. For example: C:\Temp\Cyberark[latest release]

    Do not run the upgrade from your user desktop due to Microsoft maximum file path length limitations.

    h

    Copy the GPO Hardening package to the domain server and extract the zip package.

    For both CPM and PSM:

    Copy the Unified GPO hardening zip package downloaded in #e above and extract it.

    Only PSM:

    Extract Privileged Session Manager zip file downloaded in #e above, copy over the CyberArk Hardening - In Domain - PSM.zip file and extract it.

  3. Disable the antivirus agent if it is installed on your server.

  4. For systems with PSM high availability, ensure minimal downtime by temporarily diverting traffic from the upgrading PSM.

    When diverting a platform that is defined for a specific PSM to a different PSM, any targets that are defined to connect with the specific PSM will not be accessible.

    1. In the Privilege Cloud Portal, access each Windows platform and redirect it to an alternate non-upgrading PSM ID:

      Go to Administration > Platform management and in each platform select Manage PSM connector.

    2. Select the pencil icon at the top of the window and from the list of PSMs, select a non-upgrading PSM. This directs the platform to that PSM.

    3. Upgrade the PSM which currently should not have any mapped platforms.

    4. Repeat steps a-b and now remap the platforms to the newly upgraded PSM.

    5. Repeat this process for all other PSM servers that require upgrading.

    6. Revert to your original PSM policies.

  5. Stop the following services:

    • PSM: Cyber-Ark Privileged Session Manager

    • CPM: CybeArk Password Manager

    • Scanner: CyberArk Central Policy Manager Scanner

Step 2: Upgrade the CPM

Select one of the following tools to upgrade the CPM:

This procedure applies to both primary CPMs and DR CPMs. Be sure to select the relevant CPM type for your upgrade.

  1. In Connector Management > Connectors list, click Available upgrades to display connectors that have components with newer versions.

  2. In the connector row that indicates available upgrades, hover over the status icon or the Upgrade link to view the component(s) that can be upgraded.

  3. If the component with available upgrades is CPM, check if it is the active CPM, or if it is the passive CPM (DR CPM). Note the type of CPM for subsequent actions.

  4. In the connector list, click Upgrade and continue in the Upgrade wizard according to available upgrades:

    1. In the Upgrade wizard > Select components tab, review the list of upgradable components.

      Component

      Display

      Management Agent

      If the Management Agent currently has a newer version available, it is selected by default.

      CPM

      Displayed only if a newer CPM version is available.

    2. Select the CPM checkbox and click Next.

    3. In the Configure tab enter the following details:

      Field

      Description

      Privilege Cloud

      Indicates if your Privilege Cloud environment is Production or POC.

      By default this is set to Production.

      Retain the Production setting in the following scenarios:

      • For an operational Privilege Cloud system

      • If moving from a POC environment to an operational environment

      Select the POC option only if you are a CyberArk Support representative, or you have coordinated this with CyberArk Support.

      Installer user login name and password

      The installeruser user name (installeruser@<suffix>) and updated password. The password must be updated close to the time of the upgrade, as it expires after 24 hours.

      See Set the Installeruser password.

      CPM

      Select the type of CPM you are upgrading:

      • Active is the main CPM

      • Passive is the DR CPM

  5. Check the Status column for the Active icon which indicates the upgrade was completed successfully.

    In case of a Failure icon, perform troubleshooting steps. See troubleshooting steps and logs.

The CPM upgrade process upgrades both the CPM and the Scanner.

The procedure for upgrading an active CPM and a passive CPM (DR mode) is slightly different. Make sure to follow the instructions accordingly.

In systems with multiple CPMs, upgrade each of the CPMs in your system.

To upgrade the CPM component:

  1. Open the CPM installation package you created in Prepare the Privilege CloudConnector machine:.

     

    Make sure the location of the upgrade files on the Connector machine does not contain any spaces in the full path and folder name.

  2. In the CPM\InstallationAutomation\Installation folder, right-click > Edit the InstallationConfig.xml file.

  3. In the InstallationConfig.xml file, specify the following parameters, and make sure that you set the isUpgrade parameter to True. After editing, save the file.

    Parameter

    Description

    Username

    The name of the user running the installation.

    Valid values: Username

    Default value: Windows user

    Company

    The name of the company running the installation.

     

    Use only alpha-numeric characters and spaces. Do not include special characters in the company name.

    Valid values: Company name

    Default value: My Company

    CPMInstallDirectory

    The path where CPM is installed.

    Valid values: Pathname

    Default value: C:\Program Files (x86)\CyberArk\

    isUpgrade

    Indicates if this is a CPM upgrade or a new CPM installation.

    Valid values: True/False

    Default value: False

    Make sure you set this parameter to True.

  4. In a PowerShell window, go to CPM\InstallationAutomation\Installation and run the CPMInstallation.ps1 script as Administrator.

  5. Continue the upgrade steps according to type of CPM:

    Consider your next steps according to your CPM component mode, if active or passive. See Upgrade the Privilege Cloud Connector v12.7 and later.

    For active CPM:

    1. In the CPM\InstallationAutomation\Registration folder, right-click > Edit the CPMRegisterComponentConfig.xml file.

    2. In the CPMRegisterComponentConfig.xml file, specify the following parameters, and make sure that you set the isUpgrade parameter to True..

      After editing, save the file.

      Parameter

      Description

      Set/Enter

      accepteula

      Acceptance of the end user License agreement.

      Valid values: Yes/No

      Yes

      vaultIP

      The FQDN or specific IP of the Vault server, provided to you by CyberArk support.

      Can be found in the following file:

      C:\Program Files (x86)\CyberArk\Password Manager\Vault\Vault.ini

      Valid values: FQDN or IP address.

      FQDN: vault-<subdomain>.privilegecloud.cyberark.cloud

      vaultuser

      The name of the Privilege Cloud admin user performing the installation.

      Valid values: Username

      installeruser@cyberark.cloud.<suffix>

      username

      The CPM user name that you defined during the installation process.

      Can be found in the following file:

      C:\Program Files (x86)\CyberArk\Password Manager\Vault\user.ini

      Default value: PasswordManager

      Note: If you have multiple CPMs, each CPM will have a different app user name. For example, PasswordManager, PasswordManager1, PasswordManager2, and so on.

      Make sure to use the user name that is relevant to the specific CPM.

       

      isUpgrade

      Indicates whether the registration is for a clean installation or an upgrade.

      Valid values: True\False

      Default value: False

      True

    3. Go to CPM\InstallationAutomation\Registration and In a PowerShell window run the CPMRegisterComponent.ps1 script as Administrator. When prompted, enter the Privilege Cloud admin password:

        
      CD “<installation package Path>InstallationAutomation\Registration” .\CPMRegisterComponent.ps1

    4. In the CPM/InstallationAutomation folder, right-click > Edit the CPM_Hardening_Config.xml file, set the following parameters, and save the file:

      • In parameter PasswordManagerServicesLocalUser, set Enable=Yes

      • For three (3) instances of the parameter IsPSMInstalled, set the parameter to True

      Note the parameter settings are case-sensitive and should be entered with care.

    5. In a PowerShell window, run the CPM_Hardening.ps1 script as Administrator.

    For passive CPM:

    1. In a DR CPM, the PluginManagerUser must be added manually according to the user permissions described in Creates Local Windows Service users and configures permissions, in the topic on CPM hardening description.

      After the PluginManagerUser is added, continue to next step of hardening the CPM.

    2. In the CPM/InstallationAutomation folder, right-click > Edit the CPM_Hardening_Config.xml file, set the following parameters, and save the file:

      • In parameter PasswordManagerServicesLocalUser, set Enable=Yes

      • For three (3) instances of the parameter IsPSMInstalled, set the parameter to True

      Note the parameter settings are case-sensitive and should be entered with care.

    3. In CPM\InstallationAutomation\ open a PowerShell window and run the CPM_Hardening.ps1 script as Administrator.

      In case of an error about starting the CPM services, ignore and continue.

Step 3: Update GPO hardening

To update the GPO hardening, choose one of the following methods:

Deploy the updated GPO hardening package

  1. Download the version's Privilege Cloud Unified Hardening GPO file as described in Prepare the Privilege CloudConnector machine:.

  2. Import the GPO file to your Active Directory domain.

    1. Open the Group Policy Management Console (GPMC.msc).

    2. Create a new GPO:   

      1. Expand Group Policy Management> <yourDomain>, then right-click Group Policy Objects and select New. The New GPO window appears.

      2. In the Name field, specify a name for the Unified GPO indicating the purpose and current version (for example, Unified Hardening vN.N), and click OK.

    3. In the list of Group Policy Objects, right-click the new Hardening GPO and select Import Settings.

    4. In the Welcome to the Import Settings Wizard window, click Next, and define the following:

      Tab/field

      Action

      Backup GPO window

      Click Next.

      Backup location screen

      Click Browse and select the location where you stored the version's unified Hardening GPO settings, for example Privilege Cloud Connector Unified Hardening GPO and click OK.

      The folder path appears in the Backup Location window.

      Click Next.

      Source GPO window

      Click Next.

      Scanning Backup window

      Click Next.

      Completing the Import Settings Wizard window

      Click Finish.

      The Import window appears indicating the progress of the GPO import.
    5. When the GPO import process has completed. Click OK.
    6. After import, select the GPO and in the Settings tab verify the settings have been imported successfully.

  3. Link the GPO file to the dedicated CyberArk OU containing CyberArk servers.

    1. Make sure all Connector servers are located under the dedicated OU, so the GPO will not affect any other server.

    2. Delete the previous GPO links according to the following steps:

      • In the Group Policy Management Console, click the OU to which the current PSM and CPM GPOs are linked.

      • Right-click each of the links and select Delete. Click OK to approve.

      • If upgrading from a version prior to v13.0, click the OU to which the legacy CPM and PSM GPO files are linked and delete each of the links. The legacy CPM and PSM GPO files are no longer relevant from v13.0 onward.

        In case of customizations to the default CyberArk CPM/PSM GPO such as added Active Directory security groups or user objects, note these changes and reapply them to the Group Policy after the upgrade.

    3. In the Group Policy Management Console, right-click the OU, then select Link an Existing GPO.

    4. Select the Unified Hardening GPO and click OK. The Unified Hardening GPO policy appears in the Linked Group Policy Objects tab.

  4. It is time to restart the Connector machine. Restart the machine so it will pull the updated GPO

    -Or-

    run gpupdate /force on the upgraded machines.

  5. Optionally, to support the following functions in Privilege Cloud, customize the GPO settings according to these guidelines:

    To support

    GPO update guidelines

    Direct RDP connections

    Add the following setting to the Group Policy with the appropriate Domain Security Group(s) or Users.

    Select Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies/User Rights Assignment > Access this computer from the network (NT AUTHORITY\NETWORK SERVICE, BUILTIN\Administrators, Domain\RDPUserGroup).

    See Connect using RDP.

    Domain-level PSMConnect/PSMAdminConnect

    See Move PSM application users to the domain level.

    Take care when adding any domain-specific settings to the GPO and configure domain-specific settings according to CyberArk guidelines and documentation.

Manually add CPM and PSM hardening settings

If you want to retain customized GPO settings applied to the Connector machine, add the following hardening settings, that are part of this version. For full details about the Connector's GPO hardening parameters, see Connector GPO parameters.

  1. Open the Group Policy Management Console (GPMC.msc).
  2. Click the OU that stores your legacy CPM and PSM hardening setup.

  3. Apply the following changes, which are the updates made to the GPO settings in this version:

    Go to User Rights Assignment:

    Location: Computer Configuration\Policies\Windows Settings\Security Settings\LocalPolicies\User Rights Assignment

    Apply the following:

Policy

Setting
Adjust memory quotas for a process

NT AUTHORITY\LOCAL SERVICE, NT AUTHORITY\NETWORK SERVICE, BUILTIN\Administrators, PasswordManagerUser
Allow log on locally

BUILTIN\Administrators, PSMShadowUsers, PluginManagerUser
Log on as a service

NT AUTHORITY/LOCAL SERVICE, NT AUTHORITY/NETWORK SERVICE, PasswordManagerUser, ScannerUser
Replace a process level token

NT AUTHORITY\NETWORK SERVICE, NT AUTHORITY\LOCAL SERVICE, PasswordManagerUser

Step 4: Upgrade the PSM

Upgrade the PSM component using the installation wizard.

Before you upgrade the PSM component:

  • Make sure you have performed the preparatory steps described in Before you begin, in this topic.

  • Note that as part of the upgrade, legacy PSM logs are grouped in a zip file and copied to internal archive folders for future access if necessary.

To upgrade the PSM component:

  1. Open the PSM installation package you created in Prepare the Privilege CloudConnector machine:.

  2. Right-click Setup.exe, and then select Run as Administrator.

  3. The installation wizard appears. Click Next and follow these steps within the wizard:

    Tab/event

    Step
    Microsoft Visual C++ 2013 Redistributable Package (x64) error Ignore and click Yes to Continue

    If Connector machine is domain-joined, and you logged on with a local user, the following message appears:

    • Click Yes if you are not using the RemoteApp user experience capability.

    • Click No to stop the upgrade, log on with a domain user who is a local administrator, and start the upgrade again.

    Password Vault Web Access Environment page

    Retain the default settings and click Next .

    Vault's Connection Details page

    Retain the default settings and click Next .
    Vault's Username and Password details page

    Enter the same Privilege Cloud admin credentials used for the Connector installation(installeruser@cyberark.cloud.<suffix>) and click Next.

    API Gateway connection details page

    Optionally, to apply the PSM automatically unlock accounts capability, enter the Privilege Cloud portal hostname in the Host field:

    <subdomain>.privilegecloud.cyberark.cloud

    Otherwise, click Next .

    PKI Authentication configuration page

    Optionally, to benefit from the Smart Card authentication for RDP connection capability, select Enable PKI authentication for PSM.

    Otherwise, click Next .

    If message appears, click Yes

  4. In the Hardening page, click Advanced and enter the following selections, depending on in-domain or out-of-domain hardening solution:

    Option

    Setting

    Post-installation list

    Clear all the checkboxes

    Hardening list:

    • Run the Hardening Script

    • Post hardening tasks

    • Set up AppLocker Rules

    Retain the check marks

    Hardening list:

    • TLS hardening

    		Ensure the checkbox is selected

    Retain the checkbox setting that is automatically assigned by the installer.

    Click Next .

  5. On the Update Complete page, click Finish.

     

    You can restart the Connector machine at a later stage. In any case, you must restart the Connector machine before you can use it.

Step 5: Verify the Connector upgrade is completed successfully

  1. Review installation logs.

    Review the installation logs to make sure that there are no errors in the upgrade process.

    You can find the logs in the following locations:

    Component

    Location

    CPM

    		%USERPROFILE%\AppData\Local\Temp\CPMInstall.log

    PSM

    v13.1 and later: <Windows installation directory>\Temp\PSM\PSMInstall.log

    v13.0 and earlier: <Windows installation directory>\Temp\PSMInstall.log

  2. Verify all services are running on the Connector:

    • CPM

    • Scanner (a CPM service)

    • PSM

  3. Test PSM connectors.

    Test a few sample components, for example, Standard Windows server, Web App connection, or SSH connection.

    In the event that any of the PSM connectors are not functioning properly, ensure the relevant executables are included in the PSMConfigureApplocker.xml file. See details in Check Privilege Cloud Connector functionality.

  4. Test CPM

    On the CPM that you updated, test the password verify/change/reconcile for a managed account.

  5. Enable the existing antivirus agent, or install an industry standard antivirus software.