Skip to content

Restore HyWorks Controller

The entire HyWorks deployment can be restored from a database backup. This section describes the different restore scenarios and methods in detail.

Restoring the same HyWorks Controller version

To restore the HyWorks Controller using a backed-up database from the same Controller version, follow these steps:

Placing a backup file on the HyWorks Controller

After the backup completes successfully, the administrator must place the backup file in the correct format (.bak) in the correct location on the controller to ensure a successful restore.

Backup file format

By default, HyWorks Controller stores the backup file in zip format at the following location:

C:\Windows\TEMP\DB\BACKUP\

To restore a backup, the file must be extracted first. On extraction, the following type of file is available for restoration:

  • For an SQL Server database, the extracted file has a .bak extension.

Appropriate directory for restore

The location to restore backup files from depends on how the HyWorks Controller database is configured:

  • For HyWorks Controller with an SQL Server database, SQL Server must have write access to the directory that contains the backup file. This can be achieved in one of two ways:
    • Copy the backup file to the SQL Server backup directory. The default backup directory does not have the required permissions. Either configure the correct permissions for SQL Server, or move the file to the SQL Server installation's Backup folder. This folder works reliably for restoring the HyWorks Controller with SQL Server, and is the preferred location.
    • Configure permissions on the backup file directory: Refer to the Troubleshooting section for the steps.

Restore HyWorks Controller

Important

  • In production environments, perform the restore operation with extra care.

  • Modifying the encrypted SQL Server connection details in the HyWorks Controller Service config file requires the Encrypt-Decrypt tool.

    • For security reasons, this tool is not available on public links. Contact the Support Team to get it.

  • The restored HyWorks Controller and the source server (from which the backup was taken) should not run on the same network. Running both can cause session host servers and other modules to receive conflicting HyWorks Controller configurations and communications.

Prerequisites:

  1. An appropriate backup file in the specified file format is available for restoration. Refer to the section Backup file format.

  2. The backup file is available in the appropriate directory. Preferably, keep the backup file in the SQL Server backup folder itself if SQL Server is installed locally on the same Windows server.

    1. Default location of the SQL Server backup:

    C:\Program Files\Microsoft SQL Server\MSSQL14.SQLEXPRESS\MSSQL\Backup

Restore process using the Controller Setup wizard

Installing a new controller with a backed-up database

Steps to configure a new controller by restoring the backup database:

  1. Access the Windows server that will be configured as the HyWorks Controller, ensuring it meets the following prerequisites:

    1. All prerequisites for HyWorks Controller, such as .NET 4.5, ASP.NET 4.5, SSCE runtime, SQL Server, and Web Server (IIS roles), are configured.

    2. The server does not already have HyWorks Controller installed, since the new Controller must be created from an existing database backup.

  2. Run the HyWorks Installer with administrative rights on the server where HyWorks Controller is not yet installed.

  3. The Setup wizard launches in fresh installation mode and displays the Welcome screen.

  4. Follow the on-screen instructions until the Service Database Configuration screen appears.

  5. On the Database Selection screen, select Microsoft SQL Server as the database type if the backup file is from a SQL Server-based Controller. Provide the required information, including Database Address, Port Number, Database Name, and Authentication details, then click Next.

  6. Select the appropriate log server on the Log Database Configuration screen, then click Next.

  7. On the Restore Database screen:

    1. Select the Do you want to restore the database? checkbox.

    2. Click Browse.

    3. Browse to the location of the backup file (.bak for an SQL Server database).

    4. Select the backup file and click Next.

  8. Follow the remaining on-screen instructions, then click Install to start the installation.

  9. Wait for the installation to complete.

  10. Once installation is complete, the new HyWorks Controller is up and running with the configuration from the backup.

  11. Verify the configuration from the HyWorks Controller Management Console.

Repair the existing HyWorks Controller and restore the backup

  1. Access the Windows server to configure as a HyWorks Controller, ensuring it meets the following prerequisites:

    1. All prerequisites for HyWorks Controller, such as .NET 4.5, ASP.NET 4.5, SSCE runtime, SQL Server, and Web Server (IIS roles), are configured.

    2. The server already has HyWorks Controller installed, and it needs to be repaired to restore its configuration.

  2. Run the HyWorks Installer with administrative rights on the server where HyWorks Controller is already installed.

  3. The Setup wizard launches in Maintenance mode, showing the Repair and Uninstall options. Select Repair, then click Next.

  4. The Repair option in Maintenance mode shows different configuration screens, since most settings were already configured during the original installation. After selecting Repair, the Administrator sees the following screens:

    1. Components Selection

    2. Service Logon credentials

  5. On the Restore Database screen:

    1. Select the Do you want to restore the database? checkbox.

    2. Click Browse.

    3. Browse to the location where the backup file (.bak for SQL Server databases) is stored.

    4. Select the backup file and click Next.

  6. Continue through the Setup wizard, providing the required details on each screen, until the Confirm screen appears. Click Repair to start the repair operation using the selected option and the provided backup file.

  7. Once the repair operation completes, the existing HyWorks Controller is repaired and its database is restored from the backup file.

  8. Verify the configuration from the HyWorks Controller Management Console.

The following HyWorks Controller configuration types cannot be restored from a backup file. Do not attempt to restore these production configurations.

  • HyWorks Controller configured to use an SQL Server database on a remote machine: The backup itself fails with an error. Even if a backup file happens to be available, do not attempt to restore it.

  • HyWorks Controllers in a two-node cluster configuration: A backup can be taken successfully, but restoring the primary or secondary HyWorks Controller in a cluster configuration is not recommended.

    • Recommendation: Prepare a fresh HyWorks Controller of the same version and add it to the cluster. It automatically syncs the database from the primary HyWorks Controller, so no restore is needed.

  • Multi-node setups: Restoring a backup of a multi-node setup brings back all node entries in the cluster configuration, which results in a restored but corrupted cluster. To avoid this, do not restore backups in multi-node setups. Instead, use the following recommendations:

    • Session nodes: Session nodes do not store any node-specific data, so they never need to be restored. Remove the older nodes and install new ones, pointing them to the management nodes.

    • Management nodes, secondary:

      • In an SQL-managed database high-availability setup, the secondary management node does not need to be restored. Instead, install a new management node that points to the existing database.
      • In a HyWorks-managed database high-availability setup, freshly install the secondary management node and add it to the existing cluster; it joins the cluster as the secondary node.

    • Management nodes, primary:

      • In an SQL-managed database high-availability setup, promote the current secondary to primary and remove the old primary management node from the cluster. The new primary does not need to be restored; instead, install a new management node and point it to the existing database.
      • In a HyWorks-managed database high-availability setup, promote the current secondary to primary and remove the old primary management node from the cluster. Freshly install a new secondary management node and add it to the existing cluster.

Restore using SQL Server Management Studio

As noted in the Troubleshooting and Important sections, restoring HyWorks Controller using the Controller Setup wizard can cause some configuration issues:

  1. A new controller, identical to the current one, is prepared. Other modules in production may then start communicating with both HyWorks Controllers, which can cause issues.
  2. The new controller, created from the backed-up database, retains an entry for the old controller (the one the backup was taken from). This entry must be cleared after the new controller is fully installed.
  3. This method cannot be used for setups where SQL Server runs on a different Windows server than HyWorks Controller.

Restoring the HyWorks Controller backup using SQL Server Management Studio (SSMS) helps overcome these challenges.

Benefits:

  1. Only the database is restored at first, so no second live HyWorks Controller is created.
  2. The administrator can clean up the database and remove residual entries from the source controller.
  3. This method works even when SQL Server runs on a different server than HyWorks Controller.

Prerequisites:

  1. The backup file from the source controller is available in the appropriate directory.

  2. Preferably, keep the backup file in the SQL Server backup folder itself.

    1. Default location of the SQL Server backup folder:

    C:\Program Files\Microsoft SQL Server\MSSQL14.SQLEXPRESS\MSSQL\Backup

Part 1: Restoring the database

  1. Ensure the backup file is placed in the SQL Server backup location.
  2. Launch SQL Server Management Studio.
  3. Connect to the SQL Server instance where the backup will be restored.
  4. In Object Explorer, right-click Databases.
  5. Select Restore Database...

  6. In the Restore Database window:

    1. Select the Device option.
    2. Click Browse to select the backup file.

    1. This opens a window for adding a backup file. Click Add.

    2. This opens the default SQL Server backup location and lists the backup file copied in step 1.

    3. Select the file and click OK. The selected file now appears in the Select backup devices window.

    4. Click OK to proceed.
    5. Navigate back to the Restore Database window, which now displays all selected options.
    6. Click OK to start the restore.

  7. A progress bar appears in the Restore Database window. Once the restore completes, a confirmation message is displayed.

Part 2: Installing the controller with the restored database

  1. Copy the HyWorks Controller setup files to a Windows server that has all prerequisites installed and configured.

  2. Continue the installation until the Service Database Configuration screen appears.

  3. On the Service Database Configuration screen, provide the following details:

    1. The SQL Server details used to restore the database.

    2. The database name that matches the one restored.

    3. Credentials for the SQL Server (the source and destination SQL Server configurations should be identical to avoid failures).

  4. Click Next.

  5. A warning appears, indicating that a database with the same name already exists, and asking whether to use it.

    1. Click Yes to proceed with the installation.

  6. Configure the log database as recommended.

  7. Since the controller is being installed with an existing database, do not select the restore database option on the Restore the Database screen.

  8. Complete the remaining installation settings as per the deployment requirements and recommendations.

  9. Finish the setup. The Controller is now installed with the restored database.

Restoring a higher version of the database with an older setup

Prerequisites:

  • HyWorks Encrypt-Decrypt Tool: Used to decrypt the encrypted database connection details in service configuration files. For security reasons, this tool is not available on public links. Contact the Support Team to get it.

Consider a scenario where HyWorks hotfixes are applied to a setup that also includes database changes. The database backup taken from this setup includes all the latest changes, so it can be considered a higher version than an older, hotfix-free installer.

If only the older installer (without the hotfix) is available, using it to set up a new controller may fail because of the more recent database changes.

The following steps can be followed in such cases to restore the database:

  1. Restore the database on the target server using SQL Server Management Studio, following the steps in this section.

  2. Use the Controller's old installer (without hotfixes) to install, but specify a different database name than the one restored in step 1.

  3. Install the latest hotfixes on this setup. At this point, there are two databases: the new database used by the freshly installed Controller (with hotfixes), and the original backed-up database, both available on the same SQL Server.

  4. Download and extract the latest Encrypt-Decrypt tool on the HyWorks Controller server (see the Prerequisites section above to get the tool from Accops Support).

  5. Run the Encrypt-Decrypt tool with administrator privileges:

    1. Select Controller as the mode.

    2. Browse to the HyWorks Controller installation directory.

    3. Locate and select Edc.Service.exe in the Service folder.

    4. Click Decrypt Config to open the configuration file in decrypted mode.

    5. Edit the file to point it to the restored database.

    6. Save and close the file.

    7. Click Encrypt Config to re-encrypt the file.

    8. Save and close the file.

  6. Restart the HyWorks Controller service to apply the changes.

Important

Important

Troubleshooting

Duplicate controller entry after restore

A secondary controller entry is automatically added when HyWorks Controller is installed from a backup database on SQL Server.

To remove the secondary controller entry:

  1. Log in to the HyWorks Management Console.

  2. Navigate to Server > HyWorks Controller.

  3. Confirm that the duplicate entries belong to the same server.

  4. Click Delete next to an entry to remove it.

Manually configure permission for SQL Server on default backup directory

This one-time configuration makes backing up and restoring to the default directory more convenient and avoids permission issues on the server.

The goal is to give the MSSQLSERVER account full control over the default backup directory:

C:\Windows\TEMP\DB\BACKUP\

Follow the steps below to configure permissions on this backup folder:

  1. Log in to the server (the change must be made on the actual server, not through a network share).

  2. Select the backup folder highlighted below, then right-click it and select Properties.

  3. In the Properties window, go to the Security tab and click Edit.

  4. In the Security window, click Add.

  5. In the Add User window:

    1. Set Locations to the local server name.

    2. Type NT SERVICE\MSSQLSERVER in the name box. Do not click Check Names.

    3. Click OK. A list of matching service accounts appears. Select MSSQLSERVER, and click OK to confirm.

The service account now appears in the security settings, where its permissions can be adjusted as needed.