Upgrade Endpoint Privilege Management Reporting in BeyondInsight

The sections below detail how to upgrade the Endpoint Privilege Management Reporting (PMR) database, UI, and event collector components in your BeyondInsight (BI) instance to the latest releases. These steps are applicable only when BI is at version 23.1 or later, and when upgrading the PMR UI to 23.4 or later.

Prerequisites

The following prerequisites must in place before performing the upgrade:

• BI must be at minimum version of 23.1.
• Supports up to SQL Server 2022. If installing the Endpoint Privilege Management Reporting database on the SQL Server 2022 platform, it is recommended to use the EXE installer rather than the MSl. If you prefer to use the MSI, you must ensure that Microsoft SQL Server 2012 Native Client (x64) TLS 1.2 Support is installed on your database server.
• To use the Add To Policy functionality from the Endpoint Privilege Management Reporting > Events grid in BI, the Endpoint Privilege Management Web Policy Editor version 23.4 or later must be installed and configured with BI.
  • If installed prior to installing PMR, ensure the BeyondInsight.EPM.WebPolicyEditor.Services, BeyondInsight.EPM.ReportingGateway.Services, and BeyondInsight.EPM.EventCollector.Services are restarted after installing Endpoint Privilege Management Reporting and Endpoint Privilege Management Web Policy Editor.
• Only SQL authentication is supported between BI and the PMR database. Windows authentication is not supported. The SQL server must be in mixed mode. To configure this in SQL Management Studio:
  • Go to SQL server name > Properties > Security.
  • Select SQL Server and Windows Authentication mode.



• Remote Desktop Protocol (RDP) must be enabled on the U-Series Appliance. This is required only during the PMR upgrade and can be disabled once the upgrade is complete. To enable RDP on the appliance:
  • Go to Maintenance > Network and RDP Settings.
  • Click the toggle to turn on the Enable Remote Desktop option.

 

Upgrade BeyondTrust Endpoint Privilege Management Reporting Database

Not all upgrades of the PMR UI require an updated PMR database, as there might not be any database changes since the previous release of PMR UI in BI. Check the version of the installed BeyondTrust Endpoint Privilege Management Reporting database in Windows Control Panel > Programs and Features (or Settings > Apps & features). If it matches the version specified in the name of the PrivilegeManagementReportingDatabase MSI supplied with the latest build, you can skip this section. Otherwise, follow the steps below to upgrade the PMR database.

 

Prior to upgrading the PMR database, stop the CopyFromStaging process from running, using one of the below methods.

• If the CopyFromStaging process is being run by the SQL Server Agent job:
  • In SQL Server Management Studio, expand SQL Server Agent.
  • Right-click the PGInsertData job, and select Disable.
• If the CopyFromStaging process is being run by the Service Broker queue:
  • In SQL Server Management Studio, expand Service Broker > Queues.
  • Right-click dbo.PGScheduledJobQueue, and select Disable Queue.

 

To upgrade the PMR database, follow these steps:

1. On the server that hosts the PMR database, run the PrivilegeManagementReportingDatabase EXE file as administrator, either from the folder where it is stored or from a command prompt.
2. On the Database Server step of the wizard, ensure the existing PMR database name you are upgrading is selected.

3. Check Endpoint Privilege Management Reporting for BeyondInsight Installation and click Next.

Check this box to use SQL Server authentication for the event collector, report reader, and data admin users configured in subsequent stages of the wizard.

Windows authentication to the PMR database is not supported.

 

4. If the event collector, report reader, and data admin user accounts are already in the database, uncheck the box to create or configure the user on each of those pages in the wizard, so that new users are not created during the upgrade. If the users don’t already exist, check the box to create them. An example of creating the event collector user account is shown.

 

 

Following the database upgrade, re-enable the SQL Server Agent job or the Service Broker queue, depending on which mechanism is being used.

We recommend using the SQL Server Agent job to run the CopyFromStaging process rather than using the default Service Broker queue. To switch to using the SQL Server Agent job, execute the Create_ER_Database_Agent.sql script against the PMR database. This removes the Service Broker queue and creates and enables the SQL Server Agent job.

Upgrade BeyondTrust Endpoint Privilege Management Reporting UI

As of version 23.4, PMR in BI includes a new user interface known as PMR UI, which is based on Angular, to replace the discontinued Unified Reporting (UR) user interface which was based on the out-of-support AngularJS.

If upgrading from UR to PMR UI, the upgrade steps differ from those needed to upgrade one version of PMR UI to another.

To identify if UR is currently being used in BI, on the BI management server assuming that the previous version of PMR was installed in its default location, browse to C:\Program Files\BeyondTrust\EPM Reporting Services\ReportingGateway. If the previous UR / PMR UI installed is in a custom location, browse to the custom location instead.

• If a JAR file exists that has the name beginning with AvectoUnifiedReporting, this indicates UR is installed.
  • Follow these instructions: Option 1 - Upgrade from UR to PMR UI.
• If the JAR file starts with PMR_UI, this indicates PMR UI is installed.
  • Follow these instructions: Option 2 - Upgrade from One Version of PMR UI to Another Version.

Option 1 - Upgrade from UR to PMR UI

This section covers upgrading UR versions of PMR in BI to the latest version of PMR UI.

These steps do not apply to upgrades from one version of PMR UI to another version. That type of upgrade is covered in the next section. Please see Upgrade Endpoint Privilege Management Reporting in BeyondInsight .

Stop Services and Back Up Folders

1. From Windows Services, stop the following services:
   • BeyondTrust EPM Reporting Gateway Service
   • BeyondTrust EPM Event Collector Service
2. Back up reporting services folders as follows:
   • Go to C:\Program Files\BeyondTrust\EPM Reporting Services (or the relevant location if a custom location was chosen for the existing UR install).
   • Rename the ReportingGateway folder to ReportingGatewayUnifiedReportingBackup.
   • Rename the EventCollector folder to EventCollectorUnifiedReportingBackup.

 

Upgrade Reporting Gateway Service

1. On the BI server, run the BeyondInsight.EPM.ReportingGateway.Services MSI file as administrator, either from the folder where it is stored or from a command prompt.

2. Keep the default destination folder. This service must be installed in its default location for the PMR in BI integration to work.

 

 

If the existing reporting gateway service is installed in a custom location, when running the latest BeyondInsight.EPM.ReportingGateway.Services MSI, the default install folder in the MSI is displayed as the custom location where the existing service is located. In this case, you must change the install location to C:\Program Files\BeyondTrust\EPM Reporting Services\.

Upgrade PMR UI

Run the BeyondTrust PMR UI MSI on the BI server. The upgraded reporting gateway service starts automatically as part of the installation.

 

Upgrade the EPM Event Collector

Upgrade the Event Collector Services MSI

1. On the BI server, run the BeyondInsight.EPM.EventCollector.Services MSI file as administrator, either from the folder where it is stored or from a command prompt.

2. Keep the default destination folder. This service must be installed in its default location for the PMR in BI integration to work

 

Install the Event Collector MSI

Run the BeyondTrust EventCollector MSI on the BI server. The event collector service starts automatically as part of the installation.

 

Verify Upgrade

To confirm the upgrade is successful:

1. Reset IIS by opening a command prompt as administrator and running the iisreset command.
2. Verify you can view PMR reports from the left navigation in BeyondInsight, under Endpoint Endpoint Privilege Management > Reports.

Upgrade and Configure External Event Collector Worker Nodes

It is common to configure BI with external event collector worker nodes, which are separate from the main BI management server. If you are upgrading PMR in BI using this configuration, please follow the steps below.

1. Ensure the BI event collector worker node is installed and configured.
2. Ensure all steps detailed in the above sections for upgrading PMR in BI have been followed.
3. Verify that PMR is displaying reports in BI and that it is receiving events from an endpoint that is configured to point to the BI event collector on the BI management server. This is to verify that the end-to-end process is working and that events can flow from the endpoint to the BI event collector on the BI management server, to the PMR event collector, and finally to the PMR database.
4. Ensure that the PMR database connection setting configured in the BI console is using the DNS hostname or IP address for the PMR database server, and not localhost or 127.0.0.1. Otherwise, the external event collectors are not able to communicate with the PMR database.
5. Stop the event collector service on the external event collector node to release the lock on the existing EventCollector folder.
6. Rename the existing EventCollector folder on the external event collector node to EventCollectorUnifiedReportingBackup. This folder is renamed rather than deleted to enable rollback of the event collector upgrade to UR’s event collector, and also to retain log files.
7. Run the BeyondInsight.EPM.EventCollector.Services MSI on each event collector worker node.

This must be installed in its default location for the PMR in BI integration to work.

8. Run the BeyondTrust EventCollector MSI on each external event collector worker node. The event collector service starts automatically as part of the upgrade.
9. Configure an endpoint to point to an external event collector node and raise events. Confirm they can be seen in the PMR reports.

 

If using U-Series Appliance, before continuing on with configuration, disable RDP access again by going to Maintenance > Network and RDP Settings on the appliance and clicking the slider to turn off the Enable Remote Desktop option.

Option 2 - Upgrade from One Version of PMR UI to Another Version

This section of the guide covers upgrades from an existing version of PMR UI to a later version of PMR UI.

Stop the BeyondTrust EPM Reporting Gateway Service. This ensures that any locks on existing files are removed cleanly and that a reboot is not required.

Upgrade PMR UI

Run the BeyondTrust PMR UI MSI on the BI server. The upgraded Reporting Gateway service starts automatically as part of the installation.

 

Upgrade Reporting Gateway Service

Not all upgrades require an updated reporting gateway service, because there may not have been any changes since the previous release of PMR UI in BI. Check the version of the installed reporting gateway service (BeyondTrust EPM Reporting Gateway Service) in Windows Control Panel > Programs and Features (or Settings > Apps & features). If it matches the version in the name of the BeyondInsight.EPM.ReportingGateway.Services MSI supplied with the latest build, you can skip this section. Otherwise, follow the steps below.

1. On the BI server, run the BeyondInsight.EPM.ReportingGateway.Services MSI file as administrator, either from the folder where it is stored or from a command prompt.

2. Keep the default destination folder. This service must be installed in its default location for the PMR in BI integration to work.

 

Upgrade the EPM Event Collector

The event collector must be upgraded before the event collector services.

Upgrade the Event Collector

Stop the BeyondTrust EPM Event Collector Service. This ensures that any locks on existing files are removed cleanly and that a reboot is not required.

Run the BeyondTrust EventCollector MSI on the BI server. The event collector service starts automatically as part of the installation.

 

Upgrade the Event Collector Services MSI

Not all upgrades require an updated event collector service, because there may not have been any changes since the previous release of PMR UI in BI. Check the version of the installed event collector service (BeyondTrust EPM Event Collector Service) in Windows Control Panel > Programs and Features (or Settings > Apps & features). If it matches the version specified in the name of the BeyondInsight.EPM.EventCollector.Services MSI supplied with the latest build, you can skip this section. Otherwise, follow the steps below.

1. On the BI server, run the BeyondInsight.EPM.EventCollector.Services MSI file as administrator, either from the folder where it is stored or from a command prompt.

2. Keep the default destination folder. This service must be installed in its default location for the PMR in BI integration to work

 

Verify Upgrade

To confirm the upgrade is successful:

Verify you can view PMR reports from the left navigation in BeyondInsight, under Endpoint Privilege Management > Reports.

Upgrade and Configure External Event Collector Worker Nodes

It is common for BI to be configured with external event collector worker nodes, which are separate from the main BI management server. If you are upgrading PMR in BI using this configuration, please follow the steps below.

1. Ensure the BI event collector worker node is installed and configured.
2. Ensure all steps detailed in the sections above for upgrading PMR in BI have been followed.
3. Verify that PMR is displaying reports in BI and that it is receiving events from an endpoint that is configured to point to the BI event collector on the BI management server. This is to verify that the end-to-end process is working and that events can flow from the endpoint to the BI event collector on the BI management server, then to the PMR event collector, and finally to the PMR database.
4. Ensure that the PMR database connection setting configured in the BI console is using the DNS hostname or IP address for the PMR database server, and not localhost or 127.0.0.1. Otherwise, the external event collectors are not able to communicate with the PMR database.
5. Stop the event collector service on the external event collector node to release the lock on the existing EventCollector folder.
6. Run the BeyondTrust EventCollector MSI on each external event collector worker node. The event collector service starts automatically as part of the upgrade.
7. Run the BeyondInsight.EPM.EventCollector.Services MSI on each event collector worker node.

This must be installed in its default location for the PMR in BI integration to work.

8. Configure an endpoint to point to an external event collector node and raise events. Confirm they can be seen in the PMR reports.

 

If using U-Series Appliance, before continuing on with configuration, disable RDP access again by going to Maintenance > Network and RDP Settings on the appliance and clicking the toggle to turn off the Enable Remote Desktop option.