RN200939: How to upgrade Data Hub and the Data Hub Agent MSI instances

Purpose

The purpose of this article is to allow customers to successfully upgrade our Data Hub and Data Hub Agent products, and should be used alongside our product documentation. 

Performing a Data Hub upgrade requires the following knowledge and access requirements: 

  • Microsoft Windows Server knowledge
  • Microsoft IIS knowledge
  • Local administrative access to install and uninstall applications
  • MariaDB, MySQL or MSSQL knowledge
  • DBO access to all product related databases

 

Preparation

  • Review the documentation concerning the product version you will be upgrading to
  • Ensure that your current hardware meets or exceeds the minimum required for that version
  • Ensure that the current operating system and database product meets or exceeds the minimum required for that version
  • Ensure that the current modern web browser meets or exceeds the minimum required for that version
  • Ensure that you are aware of any known issues that are mentioned within the product documentation and knowledge base related to that version
  • Download any new software requirements (this is usually .Net Framework and .Net Core)
  • Install the following optional software to aid in troubleshooting: 
      • Notepad++ or another XML editor
      • DB Browser for SQLite or another SQLite browser
  • If multiple Data Hub Agents are in use, take note of the tasks assigned to each of them

 

Data Hub 12.2 and later

Pre-install

  1. Backup the INSTALLDIR\appsettings.json file
  2. Backup the INSTALLDIR\log4net.config file if it has been customised
  3. Uninstall Data Hub
  4. Upgrade .Net Framework if required
  5. Uninstall current ".Net Core - Web Hosting Bundle" version and install latest version required by the new Data Hub version (e.g. 12.6 = latest 6.0.x version, 14.x = latest 8.0.x version)
  6. Reboot

Installation

Install the new Data Hub through an administrative command window including MSI verbose logging parameters, or through a command window that runs as a user that has DBO access to the Data Hub application database if the database is off-box and that user is not the one that is logged into the Data Hub server (not required if SQL authentication will be used). 

  • Example Raynet branding:  SOURCEDIR>filename.msi /L*v filename.log
  • Example USU branding:  SOURCEDIR>filename.msi TRANSFORMS=USUTheme.mst /L*v filename.log

Verify installation 

  • Check the VersionHistory table within the application database to ensure that the new database version is present
  • Check the "HKLM\SOFTWARE\WOW6432Node\Raynet\RayVentory\DataHub\Install\" registry key to ensure that its string objects have the correct values.  If they do not, review the MSI log file that was created and then contact support if you are unable to identify what went wrong. 
  • Check Data Hub's IIS application pool to ensure that it is using ".Net CLR Version 4.0" as sometimes its is assigned the latest version that IIS offers instead

Post-install

IIS

If HTTPS is required, create this binding for the Data Hub web site

Default Objects

  1. Administration > Tenant Settings:  Backup Current Dashboards and Reports
  2. Data & Visualization > Dashboards & Reports:  Import > from template…

 

Update new appsettings.json and log4net.config files 

  1. Stop Data Hub's IIS application pool
  2. Transfer values from the backed up appsettings.json and log4net.config files to the new ones (DO NOT simply replace the new files with the old ones)
  3. Review and configure any options that you may now wish to utilise (refer to relevant lower section)
  4. Start Data Hub's IIS application pool
  5. Reboot

Verify product access 

  1. Confirm that logins work
  2. If upgrading from one major version to another major version you will need to re-license the product (if our License Server cannot be connected to through the internet, contact support and request a license file by providing them with your order number, the HardwareID of the newly installed Data Hub, and the person responsible for this licensed product)

 

Data Hub Agent 12.2 to 12.6

Pre-install

  1. Backup the INSTALLDIR\Raynet.RayVentory.DataHub.Agent.dll.config file
  2. Backup the INSTALLDIR\log4net.config file if it has been customised
  3. Ensure the "HKLM\SOFTWARE\WOW6432Node\Raynet\RayVentory\DataHubAgent\" registry key exists and that its string objects values reflect the existing installed version.  If they do not, refer to KB article RVY200761 to rectify this situation. 

Upgrade

Perform an in-place upgrade through an administrative command window including MSI verbose logging parameters (The "Service configuration" and "Proxy settings" MSI dialogs should already be populated, allowing you to verify that their displayed values are correct or not)

 

Post-upgrade

  1. Stop the “RayVentory Data Hub Agent” service 
  2. Transfer values from the backed up Raynet.RayVentory.DataHub.Agent.dll.config and log4net.config files to the new ones (DO NOT simply replace the new files with the old ones)
  3. Review and configure any options that you may now wish to utilise (refer to relevant lower section)
  4. Start the “RayVentory Data Hub Agent” service 

Verification 

  1. Check the "HKLM\SOFTWARE\WOW6432Node\Raynet\RayVentory\DataHubAgent\" registry key to ensure that its string objects have the correct values.  If they do not, review the MSI log file that was created and then contact support if you are unable to identify what went wrong.  
  2. Confirm that the Data Hub Agent has successfully connected to Data Hub and that it is still authorised

 

Data Hub Agent 14.0 and later

  1. Log into Data Hub with an account that is either a member of a group associated with the Administrator role (preferred) or as Data Hub's root user
  2. Create an API Key through that users Profile (make sure to take note of the key)
  3. Follow the steps for the in-place upgrade; however, when you get to the "Service configuration" MSI dialog, you will need to enter the API Key value

 

Data Hub's appSettings.json file parameters

The following parameters of interest are from 14.1 u01, so some will not exist in earlier versions. 

  • TemporaryFilesDirectory and LogsDirectory:  If the Data Hub server has more than one drive, it is recommended to specify a location on a non-system drive to protect it (double backslashes should be used)
  • passwordFormat:  Enter a regular expression for password definition governance
  • CustomUserFilter:  Allows you to use an LDAP query to restrict AD users who can log into Data Hub if AD users are being used
  • ExternalIdentityManagement:  Allows you to connect Data Hub to KeyCloak
  • Security:  Allows you to enable and configure a content security policy for modern web browser access
  • AiManagement:  Allows you to connect Data Hub to your OpenAI subscription so you can benefit from Data Hub's AI assistant
  • AllowedHosts:  Allows you to specify which domain(s) machines have to be in to access Data Hub

 

Data Hub's log4net.config file parameters

The following parameters of interest are from 14.1 u01, so some will not exist in earlier versions.  If the Data Hub server has more than one drive, it is recommended to specify a location on a non-system drive to protect it, unless Data Hub is already installed on a non-system drive (default locations shown below). 

 <appender name="RollingFile" type="log4net.Appender.RollingFileAppender">
<file value="logs/RayVentoryDataHubService.log" />
 <appender name="SecurityFileAppender" type="log4net.Appender.RollingFileAppender">
<file value="logs/DataHubSecurity.log" />

 

Data Hub Agent's Raynet.RayVentory.DataHub.Agent.dll.config file parameters

The following parameters of interest are from 14.1 u01, so some will not exist in earlier versions. 

  • DataHubUrl:  If HTTPS was not used before, then this value will need to be updated
  • TemporaryFilesDirectory:  If the Data Hub Agent server has more than one drive, it is recommended to specify a location on a non-system drive to protect it
  • ServerCertificateValidationCheck:  This should be set to false if self-signed certificates are used
  • PowerShellScriptsExecutionEnabled:  This should be set to true if you wish to use Data Hub's Powershell connector

 

Data Hub Agent's log4net.config file parameters

The following parameters of interest are from 14.1 u01, so some will not exist in earlier versions.  If the Data Hub Agent server has more than one drive, it is recommended to specify a location on a non-system drive to protect it (custom locations shown below). 

 <appender name="RollingLogFileAppender" type="log4net.Appender.RollingFileAppender">
<file type="log4net.Util.PatternString" value="G:\Temp\DataHubAgent\Agent.log" />
 <appender name="ETL" type="log4net.Appender.RollingFileAppender" >
<file type="log4net.Util.PatternString" value="G:\Temp\DataHubAgent\Agent-ETL.log" />
 <appender name="CollectorAppender" type="log4net.Appender.RollingFileAppender" >
<file type="log4net.Util.PatternString" value="G:\Temp\DataHubAgent\Collector.log" />

 

Operational verification

  1. Administration > Tenant Settings > Backup:  Backup current dashboards and reports
  2. Data & Visualization > Dashboards & Reports:  Import > from template...
    • Choose what should be overridden and select the Data Hub Agent that is used the most
  3. If multiple Data Hub Agent's are used, confirm that they still have the same tasks assigned to them as before the upgrade
  4. Run at least one data collection task for each data source that Data Hub currently targets to ensure that they still work
Alex Graf -

Comments

Powered by Zendesk