XenClient Enterprise Synchronizer Migration Applicability This document is applicable to XenClient Synchronizer version 5.1. The information in this document also applies to earlier versions of XenClient, however, the procedures contained herein have only been verified with the latest version of XenClient Enterprise. Summary Migrating a Synchronizer server involves moving your current installation setup from one machine to another. This is typically done when the existing machine requires additional processing power or another performance-related upgrade. This document provides a method for migrating Synchronizer from one machine to another. NOTE: For the Migrating Synchronizer section of this document, it is assumed that a remote SQL database is used, and SQL Express was not used at installation time. For information about SQL Express installations, see the section later in this document entitled Migrating Synchronizer with SQL Express before you begin the migration process. Before beginning, make sure you are familiar with the migration process and have thoroughly backed up your user data. Migrating a Synchronizer installation will prevent clients and associated remote servers from communicating with Synchronizer (commonly referred to as the management server) for the duration of the process. NOTE: If the Synchronizer installation used SQL Express, refer to the information in that section to ensure proper interoperability. Overview of the Migration Process This section provides information about the migration process. Perform these steps first before beginning the migration: 1. Shut down the Tomcat 7.0 and SQL services on the machine where the existing Synchronizer is installed. 2. Back up the Synchronizer folder; Citrix strongly recommends preserving the entire contents of the folder. This folder is typically located in the C:\Program Files\Citrix folder; if an older version of Synchronizer is installed, the folder may be located in C:\Program Files(x86)\Virtual Computer. 3. Back up everything in the Tomcat 7.0\ssl directory; by default, this folder is located in C:\Program Files\Apache Tomcat Foundation. If you installed Synchronizer using the SQL Express database option, backup the database using the same procedure. 4. Install Synchronizer on the new machine; the same version of SQL Express should be used. 5. Shut down the Tomcat 7.0 and SQL services on the new machine. 6. Copy and replace all folders and files from your backups into the new Synchronizer folder; Citrix strongly recommends backing up all data to ensure that nothing is lost during the migration process.
7. Restart the Tomcat 7.0 and SQL services on the new machine. 8. Test connectivity to the new Synchronizer; refer to the information later in this document for more information. 9. Uninstall Synchronizer from the old machine, or reinstall the OS. Essential Backup Information This section provides information about important folders and files that must be backed up. Important files in the root directory (C:\Program Files\Citrix\Synchronizer: database.properties key.properties server.properties version.properties NOTE: If an older version of Synchronizer is installed, the Synchronizer folder may be located in C:\Program Files(x86)\Virtual Computer; newer installations are located in C:\Program Files\Citrix. Important subdirectories include: Repository VirtualMachines VmWorkingStorage NOTE: Use caution when replicating the contents of these folders. If disk space or performance issues occurred in the past, these folders may be junction points or soft links (using the mklink command) and not the actual folders themselves. Junction points must be manually copied and recreated in the Synchronizer folder to create the same junction points in the migrated system. If you have ISO images or XenClient Engine upgrade kits to back up, be sure to back up the ClientKits and IsoImages folders, as well. Citrix recommends backing up the entire Synchronizer folder to avoid missing anything when you migrate the installation. All content within the folder Tomcat 7.0\ssl (C:\Program Files\Apache Tomcat Foundation\Tomcat 7.0) should also be backed up prior to the migration:
SQL Express Users If you are migrating a Synchronizer that was installed using the SQL Express installation option instead of the remote SQL database installation option, you will also need to back up the Synchronizer database before migrating. All SQL services must be shut down prior to backing up the database without issue. For more information, refer to the section Migrating Synchronizer with SQL Express. Migrating Synchronizer with a Remote SQL Database Use the information in this section if Synchronizer was installed using the remote SQL database option. If you installed Synchronizer using a SQL Express database, refer to the section Migrating Synchronizer with a SQL Express Database later in this document. Step One Shut down the Tomcat 7.0 and SQL services on the existing Synchronizer installation. This prevents clients and associated remote office servers from communicating with Synchronizer for any functionality. NOTE: View and shut down services by opening a run prompt ( + R) and typing services.msc. Step Two With the Tomcat 7.0 service shut down, you can back up your Synchronizer directory without Tomcat interfering.; see the Essential Backup section for a list of files and directories you will need to back up. It is considered best practice to back up the entire Synchronizer folder to avoid missing anything in the process; copy these files and folders from the Synchronizer folder onto a network share, external hard drive, or another storage medium. These files will be moved onto the new machine once Synchronizer is reinstalled. NOTE: Citrix recommends that the backup is verified prior to moving to the next step in the migration process. Step Three Back up everything in the Tomcat 7.0\ssl folder (this folder contains important certificates that must be preserved). These certificates must be backed up for clients to successfully communicate with the migrated Synchronizer installation. Without these certificates, your existing XenClient Enterprise Engines, DesktopPlayer and remote office servers will permanently lose communication with Synchronizer.
Step Four Install the same version of Synchronizer on the new machine. This Synchronizer install will act as the migrated Synchronizer. When installing this, you cannot use the old database name that was used for the old Synchronizer; enter a new database name to avoid a naming conflict at install time. Step Five Installing Synchronizer on the new machine will restart the machine and then start the Tomcat 7.0 service. After the system reboots, shut down the Tomcat 7.0 and SQL services on the new machine to take Synchronizer offline. Step Six Restore and replace all critical folders and files from your backups into the new Synchronizer and new Tomcat 7.0\ssl directory. Refer to the Essential Backup section for a list of necessary files and folders. Tomcat s SSL directory now contains valid certificates for the existing XenClient Engines. The new Synchronizer directory now contains all user backups, imported ISOs/VHDs, as well as other important files that came from the old Synchronizer backup. Replacing all of the properties files resolves the issue identified in Step 4, where the old database name was not recognized by the Synchronizer installer. The database.properties file allows the new Synchronizer to communicate with SQL using the old credentials. Once the database.properties file is replaced from your backup, you can delete the empty database that was created when installing the new Synchronizer. Step Seven Start the Tomcat 7.0 service on the new machine. The new Synchronizer is now online. NOTE: Verify connectivity to the database. See Verifying Connectivity later in this document. Step Eight Verify that an existing client machine can communicate with the new Synchronizer by performing a check for updates from the action menu. If the Engine does not output an error message, you can assume that the client/server relationship has not been broken by this process. Note: If the management server s IP address or machine name changed after the migration, use the Engine s System Summary Control Panel to update the Server field to match the management server s address. To further verify that this process has worked, publish a new version of a virtual machine and then assign the new version to an existing client machine. If the engine is able to download and install the new version, you can be certain that there is no issue with the engine communicating with the Synchronizer.
Other ways to verify connectivity between Synchronizer and an Engine (commonly referred to as a client) include: alternately assigning a new VM to an Engine. After assigning it, use the Engine s Activity Center Control Panel to manually check for updates; if the Engine begins downloading a VM, communication is established. creating a faux policy in Synchronizer and assigning it to the client. After assigning the policy, use the Activity Center Control Panel to manually check for updates. If the policy is implemented on the client, communication exists. Step Nine In the event that client machines (those running XenClient Engines) are unable to communicate with the new Synchronizer (for example, the check for updates action yielded an error message indicating that an Engine was unable to communicate with the management server), there are a number of steps you can take to verify connectivity. In some cases, shutting down Tomcat 7.0 on the new machine, then restarting it on the older machine reverts the changes and returns the machines to the original state. If, however, all Engines are communicating with the new Synchronizer, you can safely uninstall Synchronizer from the old machine and treat the new machine as if it contained the old installation. Before finalizing the migration, consider the following: Try to register a new Engine to Synchronizer If a VM was not published or downloaded previously, attempt to do so. Take backups from an existing system and verify that Synchronizer is accessible both from the Engine and management server Verify that Synchronizer s Software Library contains the desired packages Create a new file and place it into the FileImport folder; import it into Synchronizer s Software Library Request diagnostics from an Engine; verify that the information is sent to Synchronizer Verify the licenses are correct. Verify AD connectivity by importing an object, or another related task. Migrating Synchronizer with SQL Express Migrating a Synchronizer installation that used the SQL Express installation option (instead of a remote SQL database) requires an additional backup the local Synchronizer database. Ensure that, along with Tomcat 7.0, the SQL service is shut down on the machine with the old Synchronizer before beginning the migration. You must back up your Synchronizer database (from the SQL Express directory) along with the files and folders listed in the Essential Backup Information earlier in this document.
From here, the migration process is similar to a remote SQL installation. You can follow the steps listed above for most of the migration process. There are, however, some additional differences: You must install the same version of Synchronizer on the new machine to ensure that the same version of SQL Express is used on the new machine as well. When installing Synchronizer, supply a temporary database name (different than the one used on the old Synchronizer) to proceed through the installation; this avoids naming conflicts later in the installation process. Once the new machine restarts after installation, shut down the Tomcat 7.0 and SQL services on the new machine. You must then import the old database into SQL Express and then copy all of the files from the Essential Backup Information section of this document into the Synchronizer and Tomcat 7.0\ssl folders. NOTE: For more information on importing and exporting SQL Server elements, refer to the Microsoft Developer Network. Copying the database.properties file will point you to the old IP address where SQL Express used to exist. This is not desired. To update this with the new IP address, open database.properties in a text editor (Notepad works). Edit the contents of the file to correspond to your existing database and IP address. For example, an existing file contains the string below: mgmt.srv.database.url=jdbc:sqlserver://localhost;instancename=sqlexpre SS;databaseName=NxTop_Center Where localhost represents the address of your old Synchronizer and SQL Express database. If a remote SQL database installation option was chosen during the Synchronizer installation, an existing file may resemble: mgmt.srv.database.url=jdbc:sqlserver://10.204.251.19:1433;databasename =Sync_DBNAME;integratedSecurity=true Where 10.204.251.19 is the IP address of your old Synchronizer and SQL remote database. Your new Synchronizer will have a different IP address than the old one, so you will need to modify this file to reflect the new IP address where the database is now held. Assuming that you simply imported the database in SQL Express and did not modify the name, you can simply update the database.properties file with the IP address of your new Synchronizer and SQL Express installation. Save the file and restart Tomcat 7.0 and all SQL services. NOTE: This extra process is not required with a remote SQL installation because the IP address does not change. Replacing the database.properties file with one from the previous installation is satisfactory with a remote SQL installation.
Verifying Connectivity After bringing the new Synchronizer online, verify connectivity: 1. Open a Web browser. 2. Browse to Synchronizer: https://servername:8443/mgmtconsole 3. Repeat this process from a remote server to further ensure connectivity. NOTE: If either method fails to connect to the management server, connection to and from an Engine will also fail. Important connectivity considerations If these methods of connecting to Synchronizer are successful, yet the Engine fails to connect to it using the Check for Updates method via the Engine Activity Center Control Panel, use the Test Network Connection action in the Related Tasks section of the Wired and Wireless Control Panel to test connectivity between an Engine and Synchronizer. To verify connectivity to the Engine: 1. Open the Engine Control Panel. 2. Locate the Wired and Wireless networking Control Panel. 3. In the Related Tasks section of the Control Panel (located in the left panel of the interface), select Test. 4. In the Test Your Network Connection screen, enter the IP address of the management server. 5. Click OK to test the connection.
If pinging the server from the Engine is successful, the connectivity problem is likely caused by a misconfigured server address in the Server field of the Summary Screen Control Panel in the Engine. If the server address is correct in the Engine Summary Screen Control Panel, and the ping between the Engine and Synchronizer is successful yet the Engine cannot connect to Synchronizer, there could be a problem with certificates; in some cases, copies of these files during the migration could fail. In such cases, Citrix recommends that you review the nxtop.log file on Synchronizer for information about the Engine connection with the server; an improper certification authentication event will be noted in the log file.