Documentation forWeb Help Desk

Upgrade WHD to the latest version

This section describes how to upgrade WHD from a currently-supported version to the latest version. Be sure to determine your upgrade path before you get started.

Upgrading WHD may add new database tables, but the procedure does not impact your database and database table data. See Database migration options for details.

Prepare for the upgrade

  1. See the upgrade gotchas to troubleshoot errors that may appear during the upgrade.

  2. If you have a test or staging environment, SolarWinds recommends testing the upgrade first. You cannot roll back an installation once it is completed.

  3. Review the instructions below for upgrading a non-FIPS and FIPS deployment.

Upgrade a non-FIPS deployment

If you are running WHD 12.7.6 or earlier with an embedded PostgreSQL database, upgrade to WHD 12.7.7 first. See How to upgrade Web Help Desk to version 12.7.7 using PostreSQL as the database for instructions. When you are finished, upgrade to the latest release. See Upgrade with FIPS disabled for instructions.

If you are located outside the continental United States, contact Technical Support for assistance with upgrading to WHD 12.7.7 with an embedded PostgreSQL database.

If you are running WHD 12.7.6 or earlier with a MySQL or Microsoft SQL Server database, upgrade to the latest release. See Upgrade with FIPS disabled for instructions. During the upgrade, you can enable FIPS, if desired.

If you are running WHD 12.7.7 with an embedded PostgreSQL database, verify that you upgraded the PostgreSQL database to version 13.3. See How to upgrade Web Help Desk to version 12.7.7 using PostreSQL as the database for instructions. When you are finished, upgrade to the latest release. See Upgrade with FIPS disabled for instructions.

If you are running WHD 12.7.7 with a MySQL or Microsoft SQL Server database, upgrade to the latest release. See Upgrade with FIPS disabled for instructions. During the upgrade, you can enable FIPS, if desired.

If you are upgrading to WHD 12.7.12, you will be prompted to re-enter your database credentials, including the database name, username, and password. Locate your database credentials before you perform the upgrade.

Upgrade a FIPS deployment

If you are running WHD 12.7.6 or earlier, upgrade to WHD 12.7.7 first. When you are finished, upgrade to the latest release. See Upgrade with FIPS enabled for instructions.

If you are running WHD 12.7.7, upgrade to the latest release. See Upgrade with FIPS enabled for instructions.

If you are upgrading to WHD 12.7.12, you will be prompted to re-enter your database credentials, including the database name, username, and password. Locate your database credentials before you perform the upgrade.

Perform the upgrade

This section describes how to upgrade your WHD FIPS or non-FIPS or FIPS deployment to the latest release.

See Web Help Desk Previous Version Documentation to access installation and administrator guides for WHD 12.5.2 and later. See System requirements for a list of supported Microsoft SQL Server, MySQL, and PostgreSQL databases.

Upgrade with FIPS disabled

Perform the following steps to upgrade WHD with FIPS currently disabled in your deployment. If required, you can enable FIPS during the upgrade.

The upgrade procedure replaces the tomcat_web_template.xml file with an updated file that includes the new version settings.

  1. Back up your data.
    1. Back up your WHD server.

    2. Back up any database server associated with WHD.

      If you have an embedded PostgreSQL database, navigate to <WebHelpDesk> and back up the pgsql9 directory to a safe location.

    3. Navigate to <WebHelpDesk>\conf\ and back up your current tomcat_web_template.xml file to an external directory.

    4. If you do not plan to enable FIPS, go to step 2.

      If you plan to enable FIPS:

      • Navigate to <WebHelpDesk>\bin and back up the nss-x64 directory to a safe location. This directory includes the Network Security Services (NSS) libraries required to enable FIPS.
      • Navigate to <WebHelpDesk>\conf\additional and back up the fips-140-2 directory to a safe location. This directory includes files used to support a FIPS configuration.
  2. (Optional) Select a database that supports failover clusters.

  3. (SQL Server and MySQL only) Install the database management tools.

    If you use the non-embedded, non-default SQL Server or MySQL as your primary database, install the database engine and management tools according to the instructions included with your software.

    Install the database on a dedicated drive with at least 20 GB of space to accommodate the database engine, management tools, help desk tickets, and ticket file attachments.

  4. (MySQL only) Prepare the time zone tables.

    If you use the non-embedded, non-default MySQL as your primary database, install the database and manually populate your time zone system tables with data.

    Beginning in version 12.5, you can search for tickets using two new qualifiers:

    • Due Date
    • First Call Resolution

    These qualifiers rely on data located in four MySQL system tables:

    • time_zone
    • time_zone_name
    • time_zone_transition
    • time_zone_transition_type

    These tables exist when you install MySQL in your deployment, but are not populated by default with data.

    WHD requires this data because Due Date and First Call Resolution qualifier logic is implemented from within the database. If the database is missing time zone data, these qualifiers will not work properly.

    Be sure to manually populate these system tables with time zone data. See the MySQL website located at https://www.mysql.com and follow the instructions for MySQL Server time zone support.

    You can check the system tables by executing the following query:

    SELECT * FROM mysql.time_zone

    If the query does not create new table rows, the tables are not populated with data.

  5. (New SQL Server implementation only) Enable TCP/IP.

    If you are migrating to SQL Server for your primary database, configure the following settings in the SQL Server Configuration Manager.

    Setting Value
    TCP/IP Protocol Enabled in SQL Server Network Configuration > Protocols for SQL 20xx
    IP Address

    127.0.0.1 (if installed on the WHD server)

    Server IP address (if installed on a separate server)
    TCP Port 1433
    TCP Dynamic Ports Blank

  6. (New SQL Server implementation only) Create and configure your database.

    If you are migrating to SQL Server for your primary database, configure the following settings in the SQL Server Management Studio for SQL Server to create and configure SQL Server to the WHD database instance.

    Setting Value
    SQL Server Authentication Enabled
    Login Name whd
    SQL Server Authentication: Password

    Enabled and configured
    SQL Server Authentication: 
    Enforce password expiration    		 Disabled
    SQL Server Authentication: 
    User must change password at next login    		 Disabled
    Database name whd
    Database owner whd

  7. (macOS only) Update your Oracle Java Database Connector (JDBC) driver (if applicable).

    WHD for macOS includes an embedded Java Virtual Machine (JVM). If you are running an external Oracle JVM, WHD preserves your Java settings during the installation procedure and continues using the external Oracle JVM.

  8. (macOS only) If you configured WHD with a PostgreSQL database, allocate additional shared memory to run the database.
    1. Open a Terminal window.
    2. Log in as root.

    3. Execute the following commands:

      sysctl -w kern.sysv.shmmax=33554432

      sysctl -w kern.sysv.shmmin=1

      sysctl -w kern.sysv.shmmni=256

      sysctl -w kern.sysv.shmseg=64

      sysctl -w kern.sysv.shmall=8192

    4. Close the terminal window.

  9. Verify all Tech accounts. If you recently upgraded from WHD 12.5.2, ensure that:

    • All techs have client accounts (authenticated through LDAP) linked to their tech accounts.
    • All tech user names do not match any new or existing client user names.
  10. Get the installer.
    1. Log in to the Customer Portal.
    2. Click Downloads > Download Product.
    3. Click the Products drop-down menu and select Web Help Desk (WHD).
    4. Click the Licenses drop-down menu and select a license.
    5. Download the WHD 12.8.2 installer for your operating system.
    6. Save the installer to your WHD server.
    7. Click Account > Log out to exit the Customer Portal.

  11. Stop the WHD service.

  12. Double-click the new WHD installer.

  13. When prompted, accept the upgrade terms.

    When the installer is completed, do not initialize the database.

  14. If you are connected to an embedded PostgreSQL database, go to step 15.

    If you are connected to an SQL Server or MySQL database, perform the following steps to re-establish a secure connection to your current WHD database.

    1. Select Use Custom SQL database (advanced).

    2. Click the Database Type drop-down menu and select your database type. For example, Microsoft SQL Server 2008+.

    3. In the Host field, enter the IP address or hostname of the SQL database server.

    4. In the Port field, enter the SQL server port number. The default port is 1433.

    5. In the Database Name field, enter then name of the SQL database instance.

    6. In the Username field, enter the name of your local SQL account.

    7. In the Password field, enter the password of your local SQL account.

    8. Click Test to test the database connection.

      When the procedure is completed, a message displays stating that the connection is good.

      If the results display an error, follow the instructions on your screen, make the necessary changes, and then click Create.

    9. Click Next.
    10. Go to step 16.

  15. Set up your PostgreSQL database connection. This step will re-establish a secure connection to your current WHD database.

    1. Select Embedded PostgreSQL database (recommended).

    2. In the Database Name field, enter the name of your existing PostgreSQL database.

    3. In the Username field, enter the user name currently assigned to the database.

    4. In the Password field, enter the current password for the PostgreSQL database.

    5. In the Admin username field, enter the current username of the PostgreSQL administrator who manages this database.

    6. In the Admin password field, enter the password for the administrator account.

    7. Click Create.

      When the procedure is completed, the installer displays a message stating that the database connection is established.

      If the results display an error, follow the instructions on your screen, make the necessary changes, and then click Create.

    8. Click Next.

  16. If prompted, select vcredist_64.exe and install the Visual C++ Redistributable Packages for Visual Studio 2013 in your <WebHelpDesk> directory. The package components are required to run C++ applications in Visual Studio 2013 for a 64-bit environment.
  17. When the upgrade is completed, close all web browsers.

  18. Update the Apache Tomcat configuration file.

    1. Navigate to <WebHelpDesk>\conf\ and open your new tomcat_web_template.xml file in a text editor.
    2. Open your backup tomcat_web_template.xml file in a text editor.
    3. Apply your personal settings from the backup file to the new file.
    4. Save and close the new file.
    5. Close the backup file.

  19. (macOS 10.13.x only) If your WHD server is running macOS 10.13.x (High Sierra), turn off GNU zip (gzip) compression in the Apache Tomcat server template file.

    See this KB article for details.

  20. (Optional) Increase the Java Virtual Machine (JVM) memory.

    WHD requires additional max heap memory than the JVM default. After you complete the upgrade, increase the MAXIMUM_MEMORY value in the whd.conf file.

    See this article for details.

  21. If you are enabling FIPS, go to step 23.

    If are not enabling FIPS, start the WHD service.

  22. (PostgreSQL database only) If you migrated WHD to a new server, restore the embedded PostgreSQL database on the new host server.

  23. Log in to the WHD Administrator Console as an administrator.

  24. Check all Tech accounts.

    If you recently upgraded from WHD 12.5.2, ensure that all Techs can access their Tech account through their Client account or their WHD tech user name and WHD password.

  25. (PostgreSQL database only) Change the default PostgreSQL database credentials. This step is required to access Web Help Desk after the database upgrade.
  26. (PostgreSQL database only) Upgrade the PostgreSQL database to the latest version.

  27. If you do not plan to enable FIPS, complete the upgrade.

    If you plan to enable FIPS, enable your FIPS deployment.

    Go to Task 1 in Enable FIPS in an existing deployment located in the WHD Administrator Guide to continue the upgrade.

    After you enable FIPS 140-2 compliant cryptography in your WHD deployment, you cannot revert back to your previous configuration.

Upgrade with FIPS enabled

Perform the following steps to upgrade WHD with FIPS currently enabled in your deployment.

The upgrade procedure replaces the tomcat_web_template.xml file with an updated file that includes the new version settings.
  1. Back up your data.
    1. Back up your WHD server.

    2. Back up any database server associated with WHD.

      If you have an embedded PostgreSQL database, navigate to <WebHelpDesk> and back up the pgsql9 directory to a safe location.

    3. Navigate to <WebHelpDesk>\conf\ and back up your current tomcat_web_template.xml file to an external directory.

    4. Navigate to <WebHelpDesk>\bin and back up the nss-x64 directory to a safe location. This directory includes the Network Security Services (NSS) libraries required to enable FIPS.

    5. Navigate to <WebHelpDesk>\conf\additional and back up the fips-140-2 directory to a safe location. This directory includes files used to support a FIPS configuration.
  2. (Optional) Select a database that supports failover clusters.

  3. (SQL Server and MySQL only) Install the database management tools.

    If you use the non-embedded, non-default Microsoft SQL Server or MySQL as your primary database, install the database engine and management tools according to the instructions included with your software.

    Install the database on a dedicated drive with at least 20 GB of space to accommodate the database engine, management tools, help desk tickets, and ticket file attachments.

  4. (MySQL only) Prepare the time zone tables.

    If you use the non-embedded, non-default MySQL as your primary database, install the database and manually populate your time zone system tables with data.

    Beginning in version 12.5, you can search for tickets using two new qualifiers:

    • Due Date
    • First Call Resolution

    These qualifiers rely on data located in four MySQL system tables:

    • time_zone
    • time_zone_name
    • time_zone_transition
    • time_zone_transition_type

    These tables exist when you install MySQL in your deployment, but are not populated by default with data.

    WHD requires this data because Due Date and First Call Resolution qualifier logic is implemented from within the database. If the database is missing time zone data, these qualifiers will not work properly.

    Be sure to manually populate these system tables with time zone data. See the MySQL website located at https://www.mysql.com and follow the instructions for MySQL Server time zone support.

    You can check the system tables by executing the following query:

    SELECT * FROM mysql.time_zone

    If the query does not create new table rows, the tables are not populated with data.

  5. (New SQL Server implementation only) Enable TCP/IP.

    If you are migrating to Microsoft SQL Server for your primary database, configure the following settings in the SQL Server Configuration Manager.

    Setting Value
    TCP/IP Protocol Enabled in SQL Server Network Configuration > Protocols for SQL 20xx
    IP Address

    127.0.0.1 (if installed on the WHD server)

    Server IP address (if installed on a separate server)
    TCP Port 1433
    TCP Dynamic Ports Blank

  6. (New SQL Server implementation only) Create and configure your database.

    If you are migrating to Microsoft SQL Server for your primary database, configure the following settings in the SQL Server Management Studio for SQL Server to create and configure SQL Server to the WHD database instance.

    Setting Value
    SQL Server Authentication Enabled
    Login Name whd
    SQL Server Authentication: Password

    Enabled and configured
    SQL Server Authentication: 
    Enforce password expiration    		 Disabled
    SQL Server Authentication: 
    User must change password at next login    		 Disabled
    Database name whd
    Database owner whd

  7. (macOS only) Update your Oracle Java Database Connector (JDBC) driver (if applicable).

    WHD for macOS includes an embedded Java Virtual Machine (JVM). If you are running an external Oracle JVM, WHD preserves your Java settings during the installation procedure and continues using the external Oracle JVM.

  8. Verify all tech accounts. If you recently upgraded from WHD 12.5.2, ensure that:

    • All techs have client accounts (authenticated through LDAP) linked to their tech accounts.
    • All tech user names do not match any new or existing client user names.
  9. Get the installer.
    1. Log in to the Customer Portal.
    2. Click Downloads > Download Product.
    3. Click the Products drop-down menu and select Web Help Desk (WHD).
    4. Click the Licenses drop-down menu and select a license.
    5. Download the WHD 12.8.2 installer for your operating system.
    6. Save the installer to your WHD server.
    7. Click Account > Log out to exit the Customer Portal.

  10. Stop the WHD service.

  11. Double-click the new WHD installer.

  12. When prompted, accept the upgrade terms.

    When the installer is completed, do not initialize the database.

  13. Re-establish a secure connection to your current WHD database.

    1. Select Custom SQL database (advanced).

    2. Click the Database Type drop-down menu and select your database type. For example, Microsoft SQL Server 2008+.

    3. In the Host field, enter the IP address or hostname of the SQL database server.

    4. In the Port field, enter the SQL server port number. The default port is 1433.

    5. In the Database Name field, enter then name of the SQL database instance.

    6. In the Username field, enter the name of your local SQL account.

    7. In the Password field, enter the password of your local SQL account.

    8. Click Test to test the database connection.

      When the procedure is completed, a message displays stating that the connection is good.

      If the results display an error, follow the instructions on your screen, make the necessary

      changes, and then click Create.

    9. Click Next.

  14. If prompted, select vcredist_64.exe and install the Visual C++ Redistributable Packages for Visual Studio 2013 in your <WebHelpDesk> directory. The package components are required to run C++ applications in Visual Studio 2013 for a 64-bit environment.
  15. When the upgrade is completed, stop the WHD service.

  16. Update the Apache Tomcat configuration file.

    1. Navigate to <WebHelpDesk>\conf\ and open your new tomcat_web_template.xml file in a text editor.
    2. Open your backup tomcat_web_template.xml file in a text editor.
    3. Apply your personal settings from the backup file to the new file.
    4. Save and close the new file.
    5. Close the backup file.

  17. (macOS 10.13.x only) If your WHD server is running macOS 10.13.x (High Sierra), turn off GNU zip (gzip) compression in the Apache Tomcat server template file.

    See this KB article for details.

  18. (Optional) Increase the Java Virtual Machine (JVM) memory.

    WHD requires additional max heap memory than the JVM default. After you complete the upgrade, increase the MAXIMUM_MEMORY value in the whd.conf file.

    See this KB article for details.

  19. Navigate to <WebHelpDesk>/conf/additional/fips.

  20. Open the WebHelpDesk - clean install directory.
  21. Navigate to <WebHelpDesk>.

  22. Paste the files to the root directory, overwriting all targeted directories as prompted.

    If you have an embedded PostgreSQL database, paste the files to the <WebHelpDesk>\pgsql9 directory.

  23. (Embedded PostgreSQL only) Restore the database from the backup you performed in step 1.
  24. Start the WHD service.

  25. Open WHD.

    The application locates and upgrades your database.

    Next, the Login page displays.

  26. Log in to WHD.

  27. Complete the upgrade.

Complete the upgrade

Reauthorize the incoming mail account, outgoing mail account, and the optional Orion Platform integration to incorporate the updated database connection settings.

  1. Reauthorize the incoming mail accounts configuration.

    1. Click Setup > email > Incoming Mail Accounts.

    2. In the email Account column, click your primary incoming mail account.

      For example:

    3. In the Authentication Mode field under Client Secret, click Reauthorize.

    4. Click Save.

      The OAuth authentication mode is reauthorized.

  2. Reauthorize the outgoing mail account on the SMTP server.

    1. Click Setup > email > Outgoing Mail Accounts.

    2. In the Outgoing Mail Accounts column, click your primary outgoing mail account.

    3. In the SMTP Password field, re-enter your SMTP password.

    4. Click Save.

      Your outgoing email account is re-authorized for your outgoing email. Additionally, this option is required to integrate your WHD calendar with Google Gmail or Microsoft Exchange.

  3. (Orion Platform integrations only) Verify the Orion Platform integration.

    1. Verify that you can receive alerts from the Orion Platform.

      See Test the alert filtering rules for instructions.

    2. Click Setup > Assets > Discovery Connections.

    3. Under Asset Discovery Connections, click a connection.

    4. Re-apply the password, verify that the discovery connection is set up correctly, and then click Save.

    5. Repeat step b through step d for each additional discovery connection.

    6. Click Setup > Clients > AD/LDAP Connections.

    7. In the Connections column, click an LDAP connection.

    8. Verify that the connection is set up correctly, and then click Save.

  4. Complete the upgrade checklist.

After you have performed all steps in the upgrade checklist, your upgrade is complete.