Upgrade On-Premises Deployments

There are several steps you need to go through for the On Premises deployments. Be sure to download the latest build for the version of PMC that you are upgrading to. It is in the File Downloads area of the Customer Support Portal.

 

PMC 2.4 SR1 is compatible only with Reporting database 5.5. If you do not intend to upgrade your Reporting database to 5.5, please do not proceed with the upgrade of PMC.

Upgrade the Management Database

You need to upgrade the Avecto.IC3.Database.Management database before you upgrade the application.

Please review the Release Notes to see if there are any changes to the database. If there are no changes to the database, you can proceed to the application.

For more information, please see Upgrade the Application.

Upgrade the Management Database

  1. Connect to your database using SQL Server Management Studio.
  2. Expand the Databases node under Object Explorer.
  1. After you successfully connect, expand the Databases node under Object Explorer, right-click on the Avecto.IC3.Database.Management database, and click New Query.
  2. Select File > Open > File, navigate to the SupportFiles folder, and locate SQL.zip for the version you are upgrading to.
  3. Unzip SQL.zip and locate the Avecto.IC3.Database.Management.sql script. This contains all the database migrations required to perform an upgrade.
  4. Run the script by pressing F5, or click Execute.

Copy and execute the following query to confirm that your upgrade was successful: 

Select Top (1000) [MigrationID]
   ,[ContextKey]
   ,[Model]
   ,[ProductVersion] 
FROM [dbo].[__MigrationHistory]

Upgrade the Application

Update Service Fabric Runtime

Run the update from any machine that can communicate with the cluster that has the runtime and SDK installed.

For more information, please see Upgrade the Service Fabric version that runs on your cluster.

Update Cluster Nodes with Internet Connectivity

    Connect-ServiceFabricCluster
    -ConnectionEndpoint $ClusterEndpoint `
    -KeepAliveIntervalInSec 1000 `
    -X509Credential `
    -ServerCertThumbprint $ServerCertThumbprint `
    -FindType FindByThumbprint `
    -FindValue $ClusterAdminThumbprint `
    -StoreLocation CurrentUser `
    -StoreName My
  1. Run PowerShell.exe as an administrator, paste the following code in, and press Return. You must provide the following parameters:
    • $ClusterEndpoint: This is your PMC DNS with the port number 19000 postfixed. For example, $mydns$:19000
    • $ServerCertThumbprint: This is the thumbprint of your SSL certificate.
    • $ClusterAdminThumbprint: This is the thumbprint of your IC3ClusterAdmin certificate.
  1. Type Get-ServiceFabricClusterUpgrade into PowerShell to check the current Service Fabric Runtime version. Make a note of the TargetCodeVersion.
  2. Type Get-ServiceFabricRegisteredClusterCodeVersion into PowerShell to retrieve a list of Service Fabric versions you can upgrade to.
  1. Type the following into PowerShell to start a cluster upgrade to an available version listed in the output of the previous step. Replace <codeversion> with the version you are upgrading to.
Start-ServiceFabricClusterUpgrade -Code -CodePackageVersion "<codeversion>" -Monitored -FailureAction Rollback
  1. Monitor the upgrade to check it has completed successfully. You can view the status of the upgrade under UpgradeDomainStatus when you run the below command and the TargetCodeVersion will be updated to the version that you upgraded to.
Get-ServiceFabricClusterUpgrade

Update Cluster Nodes with no Internet Connectivity

  1. Download Microsoft_ServiceFabricRuntime.cab from a machine with an internet connection.
  2. Run PowerShell.exe as an administrator, paste the following code in, and press Return. You must provide the following parameters:
    • $ClusterEndpoint: This is your PMC DNS with the port number 19000 appended to it. For example, $mydns$:19000
    • $ServerCertThumbprint: This is the thumbprint of your SSL certificate.
    • $ClusterAdminThumbprint: This is the thumbprint of your IC3ClusterAdmin certificate.
  1. Type Get-ServiceFabricClusterUpgrade into PowerShell to check the current Service Fabric Runtime version. Make a note of the TargetCodeVersion.
  2. For the remaining steps, visit Microsoft's website as indicated below.

For more information, please see the relevant section of the article Upgrade the Service Fabric version that runs on your cluster.

Enable WinRM with SSL on the Node Hosting the Portal

  1. Connect to the machine hosting the portal and copy the Enable-WinRMWithSSL.ps1 script from the build folder to the node hosting the desktop.
  2. Run PowerShell as an administrator and navigate to the location of Enable-WinRMWithSSL.ps1.
  3. Type .\Enable-WinRMWithSSL -SubjectName $NodeHostingPortal -ForceNewSSLCert.

Perform Upgrade on the Deployment Machine

You need the On Prem folder for the version of PMC that you are upgrading to.

  1. Copy the Upgrades folder from the build you want to upgrade to onto the deployment machine. This contains all the files needed to prepare and upgrade your environment.

If you need to change any values in the configuration (for example, the location of the portal and connection strings) you must provide them as an argument to the PrepUpgradeConfig.ps1 script before you run it.

  1. You are now ready to run the PrepUpgradeConfig.ps1 script. If you change the location of the portal from the default value, you need to supply it as an optional argument. For example, in an elevated PowerShell window, type:
    PrepUpgradeConfig.ps1 UpdateApplicationParameters @{”Avecto.IC3.JobAgent.DeploymentType” = “0”;} -PortalWebsiteVmLocation "C:\MyFolder\iC3"
    When you press Return, you are prompted for the mandatory parameters listed below. If you did not change the location and do not need to change any other parameters, type:
    PrepUpgradeConfig.ps1 -UpdateApplicationParameters @{”Avecto.IC3.JobAgent.DeploymentType” = “0”;}
    • ClusterEndpoint: Your DNS with :19000 postfixed. For example, pmctest.example.com:19000 (https:// is not required).
    • ClusterAdminThumbprint: The thumbprint output during initial deployment for the PMC Cluster Admin certificate.
    • ServerCertThumbprint: The thumbprint of the SSL certificate.
    • PortalVmAdminUsername: The administrator user name for the node hosting the PMC portal.
    • PortalVmPassword: The password for the node hosting the PMC portal.
    • PortalVmIpAddress: The IP address of the node hosting the PMC portal.
    • ParametersConfigFilePath: The full file path of the parameter config file in the Upgrades folder. For example, C:\Users\myuser\Desktop\Upgrades\Production.3node.xml
    • WebConfigFilePath: The full file path of the web config file in the Upgrades folder. For example, C:\Users\myuser\Desktop\Upgrades\Web.Production.config

    When this script is executed, a text file containing all of the original values is output to the location in which the script is run. This must be saved to a secure location in case these values are needed. In the event that they are needed, the required value must be copied from this text file into the config file.

  1. Copy the Package.zip folder from the SupportFiles folder (the version you are upgrading to) to your deployment box and unzip it.
  1. Connect to the deployment machine (ensure you have the cluster administration *.pfx certificate portion installed on the machine before continuing).
  2. Open Powershell as admin and run the UpdateServiceFabricAppSetting.ps1 (in the Upgrades folder) script with the following parameters:
    • ClusterAddress: The DNS Name of your cluster postfixed with :19000. For example, PMCcert.PMC:19000.
    • ServerCertThumbprint: The thumbprint of the ClusterAdminCertificate.
    • ClusterAdminThumbprint: The thumbprint of the ClusterAdminCertificate (same as ServerCertThumbprint).
    • UpdateConfigParameters: The event pump service Avecto.IC3.Fabric.EndpointEventPump.EventProcessingDisabled set to true.
    .\UpdateServiceFabricAppSetting.ps1 -ClusterAddress "pmc.domain.com:19000" -ServerCertThumbprint "54761d496fe75fd4fe81a488fa709e4e79613385" -ClusterAdminThumbprint "54761d496fe75fd4fe81a488fa709e4e79613385 " -UpdateConfigParameters @{"Avecto.IC3.Fabric.EndpointEventPump.EventProcessingDisabled"  = "true";}
  3. The update will apply to each node one at a time. You can check the update status through Service Fabric Manager.
  4. Once the update is complete, run the following command in PowerShell to check if the setting is applied:
    Get-ServiceFabricApplication -ApplicationName fabric:/IC3.Fabric

    This will output the application configuration.

    The Avecto.IC3.Fabric.EndpointEventPump.EventProcessingDisabled parameter should now be set to true.

  5. Through SSMS, pause the SQL Agent job / Service broker queue, and then make sure the CopyFromStaging job has finished running.
  1. From your PowerShell instance, navigate to the UpgradeApp.ps1 script in the Upgrades folder and provide the following parameters:
    • PackagePath: The path to the unzipped package folder you copied over. For example, C:\Users\myuser\Desktop\Package
    • AppParamsPath: The location of the Production.3Node.xml file in the Upgrades folder. For example, C:\Users\myuser\Desktop\Upgrades\Production.3node.xml
    • ClusterAddress: The DNS with :19000 postfixed. For example, pmctest.example.com:19000 (https:// is not required).
    • ClusterAdminThumbprint: The thumbprint output during the deployment for the PMC Cluster Admin certificate.
    • ServerCertThumbprint: The thumbprint of the SSL certificate.
  2. The script will run and begin the upgrade process. To check the progress, navigate to Service Fabric explorer, expand the cluster, and select Applications from the tree view. In the right work pane, you will see Upgrades in progress text. Click on this to see the progress for each node. It shows the current version and the target version you are upgrading to. During the upgrade, Service Fabric displays several warnings as each domain is taken down. Upon completion of an upgrade, these warnings should be removed. During the upgrade, the policy on endpoints is still be applied and the policy remains functional.

Check for Successful Application Upgrade

You can check if your upgrade was successful by navigating to Cluster > Applications in Service Fabric. The application shown on the right should match the version you upgraded to.

Application Upgrade Issues

If an upgrade runs and fails, it will automatically rollback once it detects errors in Service Fabric. After a period of 30 minutes, these errors should be removed and another attempt at an upgrade can begin.

Error on subsequent application upgrade after failed upgrade

When the UpgradeApp script is run again, there may be an error in PowerShell (see below). However, the script will continue to run and begin the upgrade process and, assuming all parameters are correct, finish successfully.

If you receive an error that states Application type and version already exists at <path>, then the error is due to the previous failed run leaving the application type and version provisioned in Service Fabric. Running the script again will clash as it is the same version. The script itself will continue and overwrite this version.

To avoid seeing this error, you can navigate to Service Fabric explorer and manually unprovision the new version of the application before re-running the script. However, you cannot roll back to previous versions if you unprovision the application. You can do this by navigating to the Cluster > Applications > IC3.FabricType node and clicking Unprovision.

Upgrade the Portal

Finally, you need to upgrade the portal. Please follow the steps below.

  1. Log on to the jump box and then remote onto your portal VM.
  2. Create a new folder under C:\inetpub\wwwroot named with the new version number.
  3. Copy the contents of the new portal package into the folder you just created.
  4. Rename the Web.production.config file that was created previously by the PrepUpgradeConfig.ps1 script to web.config and copy into the new portal folder with the version you just created. This will overwrite the existing one.

Navigate to Sites > [your portal] in IIS.

  1. Open Internet Information Services (IIS) and navigate to Sites > iC3Portal.
  2. Under Basic Settings, select the new physical path you have created, and click OK.

 

Disable the IIS Logging Setting

In PMC 2.4 and earlier, IIS logging is enabled on the portal VM. This can fill the hard drive with log files.

You can run the following script to turn off logging. The script is available with PMC 2.4 SR1 and later.

DisableIISLogging.ps1

The script is located in DeploymentWizard\Upgrades. For example, …PMC\v2.4-1581\DeploymentWizard\Upgrades.

The deployment tool turns off IIS logging on the portal VM. When turned off, logging is disabled for all IIS sites on the portal VM. If you require logging to be enabled for any other sites, then you must enable logging at the site level for those specific sites.

Upgrade Privilege Management Reporting Database

 

You must upgrade your reporting database to 5.5 in order to use PMC 2.4.

Prerequisites

Log on to the customer portal to download the scripts from the following location: EnterpriseReporting\5.5\5.5.40\Enterprise Reporting\SQL.

  1. Ensure the event pump is turned off as outlined in the procedure Perform Upgrade on the Deployment Machine.
  2. Disable the PGInsertData SQL Agent job / Service broker queue.
  1. Wait for any CopyFromStaging job to finish.

Upgrade Steps

To upgrade a Privilege Management database using SQL scripts:

  1. The SQL scripts are provided as part of the Privilege Management installers, located in the Privilege Management Reporting release folder, which can be found in the BeyondTrust portal. Alternatively, you can contact BeyondTrust Technical Support.

There is a README file provided in this directory to assist you.

  1. Run the following SQL query to return the version of the database.

  2. select * from DatabaseVersion
  3. Execute the upgrade script where the name is the next version number and carry on applying these until the desired version is reached.

  4. For example, if your current database version is 4.3.16 and you want to upgrade to version 5.0.0, run the following scripts in order:
    1. Script_4.5.0_Updates.sql
    2. Script_5.0.0_Updates.sql

    Please check the SQL log for any errors and contact BeyondTrust Technical Support if necessary.

  1. Run and execute the following SQL query against the reporting database to return the versions in the InstallShield table:
  2. SELECT * FROM [dbo].[InstallShield]
  3. Open the InstallShield query file. This is available in the SQL folder, and is a Privilege Management Reporting artifact.
  4. Copy the relevant INSERT lines from this query file that are not included in the database table.
    For example, if the upgrade is from 5.1.1 to 5.4, you need to copy these lines:
    INSERT [dbo].[InstallShield] ([ISSchema]) VALUES (N'5.3.0          ')
    INSERT [dbo].[InstallShield] ([ISSchema]) VALUES (N'5.4.0          ')
  5. Copy these into a query against the Reporting Database and execute it.
  6. View the InstallShield table by running the query below. These values are added.
  7. SELECT * FROM [dbo].[InstallShield]

Turn on Service Fabric Components

You need to turn back on the Service Fabric settings for incoming events.

  1. Connect to the Deployment Machine (ensure you have the Cluster Administration *.pfx certificate portion installed on the machine before continuing).
  2. Open Powershell as admin and run the UpdateServiceFabricAppSetting.ps1 (in the Upgrades folder) script with the following parameters:
    • ClusterAddress: The DNS Name of your cluster postfixed with :19000. For example, PMCcert.PMC:19000.
    • ServerCertThumbprint: The thumbprint of the ClusterAdminCertificate.
    • ClusterAdminThumbprint: The thumbprint of the ClusterAdminCertificate (same as ServerCertThumbprint).
    • UpdateConfigParameters: The event pump service Avecto.IC3.Fabric.EndpointEventPump.EventProcessingDisabled set to true

    For example:

    .\UpdateServiceFabricAppSetting.ps1 -ClusterAddress "pmc.domain.com:19000" -ServerCertThumbprint "54761d496fe75fd4fe81a488fa709e4e79613385" -ClusterAdminThumbprint "54761d496fe75fd4fe81a488fa709e4e79613385 " -UpdateConfigParameters @{"Avecto.IC3.Fabric.EndpointEventPump.EventProcessingDisabled"  = "false";}
  1. The update will apply to each node one at a time. You can check update status through Service Fabric Manager.
  2. Once the update is complete, run the following command in PowerShell to check if the setting is applied:
  3. Get-ServiceFabricApplication -ApplicationName fabric:/IC3.Fabric

    This will output the application configuration.

    The Avecto.IC3.Fabric.EndpointEventPump.EventProcessingDisabled parameter should be set to false.

  1. Through SSMS, start the SQL Agent job /Service broker queue.
  2. Check the Reporting in PMC to confirm events are flowing through to the database.

Change Application Parameters Before Upgrade

You can use the script to update values in both the Production.3Node.xml or the Web.config file that are provided as part of the upgrade in the Upgrade folder, if required. You need to use the script to do this rather than edit the files directly, otherwise any changes will be overwritten by the script.

  1. Run PowerShell as an administrator and navigate to the location of the PrepUpgradeConfig.ps1 script in the Upgrades folder.
  2. To change values in the Production.3Node.xml file, use the following command:
PrepUpgradeConfig.ps1 -UpdateApplicationParameters @{"String.Name.One" = "argument"; "String.Name.Two" = "argument";}

PrepUpgradeConfig.ps1 -UpdateApplicationParameters @{"Avecto.IC3.Authentication.Domain" "https://login.microsoftonline.com/53c8dbb9-fb9b-467a-8930-f23d8e0199c9";}

  1. To change values in the Web.config file, use the following command:
PrepUpgradeConfig.ps1 -UpdateWebConfigParameters @{"String.Name.One" = "argument} 

PrepUpgradeConfig.ps1 -UpdateWebConfigParameters @{"Avecto.IC3.Log.Seq.Host" = "https://localhost:5391"}