September 4, 2013 XenClient Enterprise 5.0 Synchronizer Database Integration
Copyright 2013 Citrix Page 2 XenClient Enterprise 5.0 Synchronizer Database Integration Table of Contents Synchronizer Database Integration 3 Supported Database Versions 4 MSSQL 2012 Express vs. Standard Edition 5 Synchronizer Database Integration Notes 6 Database Access and Schema Notes 7 Database Sizing Guidelines 8 Synchronizer Installation (Bundled Database) 9 Database Option: Install MSSQL 2012 Express 10.NET 3.5 Requirement 11 MSSQL 2012 Express Configuration 12 What Gets Installed 13 Synchronizer Installation (External Database) 14 Database Option: Use Existing MSSQL Server 15 External Database Configuration 16 Database Server Credentials 17 Database Security Policy Issues 18 Synchronizer Installation: Remote Servers 19 Remote Network Connectivity Requirements 20 Remote Server Installation 21 SQL Server Browser Service 22 Dynamic Ports and Remote Synchronizer Servers 23 Database Management Operations 24 Verifying Database Connectivity in the Console 25 Verifying Database Connectivity in Log Files 26 Locating Database Files 27 Relocating Database Files 28 Changing the Database Username and Password 29 Purging Database Event Tables 30 Migrating to a Production MSSQL Server 31 Synchronizer Database Export Example 32 Synchronizer Database Import Example 33 Appendix A: Database Reporting 34
Copyright 2013 Citrix Page 3 XenClient Enterprise 5.0 Synchronizer Database Integration VHD Repository Folders Download VHD files for assigned VMs. Upload VHD files for VM backups. MSSQL Database Storage and retrieval of Java objects. Apache Tomcat Server Persistence Layer (Hibernate) Synchronizer Internal Java API Console Interface Engine Interface Engine connects on port 443. Console connects on port 8443.
Copyright 2013 Citrix Page 4 XenClient Enterprise 5.0 Synchronizer Database Integration Supported Database Versions Synchronizer 5.0Earlier Synchronizer Versions MSSQL 2005 Supported but not recommended for new deployments. Supported. MSSQL 2005 Express was bundled with pre-5.0 versions of Synchronizer. MSSQL 2008 Supported. MSSQL 2012 Supported and recommended. MSSQL 2012 Express is bundled with Synchronizer 5.0. Not Supported. Anything Else Not Supported. Microsoft SQL Server is the only supported database. See below for supported database versions.
Copyright 2013 Citrix Page 5 XenClient Enterprise 5.0 Synchronizer Database Integration MSSQL 2012 Express vs. Standard Edition ExpressStandard Max Database Size10 GB524 PB Max Memory1 GB64 GB Max CPU (Processors)14 Max CPU (Cores)416 Some data of interest from a detailed comparison between different editions of MSSQL 2012: From a technical point of view, Express should easily handle medium to large XCE deployments. But from an operational point of view, Standard Edition has advantages beyond scalability: More features such as scheduled backups. Better support available from Microsoft (presumably). General recommendations: Production XCE deployments should use production databases, regardless of size. MSSQL 2012 Express should easily handle deployments up to 100 managed endpoints. Beyond 100 managed endpoints, Standard Edition should be used instead. Source: http://msdn.microsoft.com/en-us/library/cc645993.aspxhttp://msdn.microsoft.com/en-us/library/cc645993.aspx
Copyright 2013 Citrix Page 6 XenClient Enterprise 5.0 Synchronizer Database Integration Synchronizer Database Integration Notes Synchronizer uses the database to store Java objects. Using Hibernate technology (http://www.hibernate.org).http://www.hibernate.org Database schema matches Java class definitions. Schema is undocumented and may change at any time. Synchronizer upgrade automatically handles schema evolution. VHD files are not stored in the database. They are stored in the Windows file system: VmWorkingStorage folder (uncompressed, for booting VMs in Hyper-V). Repository folders (compressed, for Engine download and upload operations). Database installation options: MSSQL may be installed on the primary Synchronizer server. Only recommended for small deployments (100 endpoints or less). MSSQL should only be used for Synchronizer, not other purposes. MSSQL may also be installed on a separate server. Recommended for large deployments. Good network communication between the primary Synchronizer server and the database server is critical.
Copyright 2013 Citrix Page 7 XenClient Enterprise 5.0 Synchronizer Database Integration Database Access and Schema Notes The database schema: Is private, undocumented, and may change at any time. Some parts are obvious, but other parts may be confusing or misleading. There are complex and non-obvious dependencies between some tables. Viewing data in the database: Not recommended, and shouldn’t be necessary for Synchronizer management. But occasional access for reporting or informational purposes should be OK. Read-only connections to the Synchronizer database are strongly recommended. Also see Database Reporting.Database Reporting Changing data in the database: Stop! Use the Synchronizer console instead, which provides a well-defined, documented, and supported framework for managing Synchronizer data. Should only be done as directed by Citrix Technical Support for data repair, or in rare cases when Synchronizer console doesn't provide needed functionality. This is potentially dangerous and precautions should always be taken: Shutdown Synchronizer first (primary and all remote servers). Backup the database first. Triple-check all SQL statements before execution.
Copyright 2013 Citrix Page 8 XenClient Enterprise 5.0 Synchronizer Database Integration Database Sizing Guidelines Sizing Guidelines For planning purposes, use 10 MB per managed endpoint. This yields: 1 GB for 100 endpoints, 10 GB for 1000 endpoints, etc. Use the maximum total endpoints across all servers (primary and remote). This is a very general guide and will be overly conservative in most cases. Excessive Database Growth Almost always caused by accumulation of entries in the event tables. The event tables may be purged, but before doing this: Check for a computer or other entity spamming Synchronizer with events. Make sure the update check interval is not set too low in the Engine policy. Recommended update check interval: N/20 in minutes (N = total number of managed endpoints). But never less than 10 minutes.
Copyright 2013 Citrix Page 10 XenClient Enterprise 5.0 Synchronizer Database Integration Database Option: Install MSSQL 2012 Express The Synchronizer installer comes bundled with MSSQL 2012 Express. When installing the primary Synchronizer, there are two database options: Install MSSQL Express This installs the full MSSQL 2012 Express server software. MSSQL 2012 Express is automatically configured for Synchronizer integration. It is expected that the MSSQL installation will be used only for Synchronizer. Use an Existing MSSQL Server See Synchronizer Installation: Integrating with an Existing MSSQ Instance.Synchronizer Installation: Integrating with an Existing MSSQ Instance
Copyright 2013 Citrix Page 11 XenClient Enterprise 5.0 Synchronizer Database Integration.NET 3.5 Requirement Microsoft.NET 3.5.1 is installed from the Windows Server Manager tool. It can't be downloaded from Microsoft (unlike other.NET versions). In Server Manager, select the Features element then click the Add Features link. MSSQL 2012 Express requires Microsoft.NET 3.5.1. The Synchronizer installer will display a warning if this version of.NET is needed but not installed. It is not necessary to cancel the Synchronizer install, but the install won't proceed until.NET 3.5.1 is available..NET Framework 3.5.1 should appear as an installable feature. Do not install WCF Activation. It is not needed and will pull in other Windows features that may interfere with Synchronizer.
Copyright 2013 Citrix Page 12 XenClient Enterprise 5.0 Synchronizer Database Integration MSSQL 2012 Express Configuration Database sa Account Password Synchronizer will be configured to use the sa account for database access. Don't forget this password. It may be needed later. Password requirements: Must be 7 characters or longer. Must include one upper-case (A-Z), one lower-case (a-z), and one digit (0-9). Non-ASCII characters and most ASCII special characters are not allowed. Allowed: underbar (_), exclamation (!), dollar ($), asterisk (*), period (.), and dash (-). Database Language This is used to specify the collation for the Synchronizer database. It generally has little effect on Synchronizer operations. But it may affect sorting of strings containing non-ASCII characters in Synchronizer console. Most configuration for MSSQL 2012 Express is done automatically by the Synchronizer installer. But two user inputs are needed.
Copyright 2013 Citrix Page 13 XenClient Enterprise 5.0 Synchronizer Database Integration What Gets Installed When MSSQL 2012 Express is installed by the Synchronizer installer, the following database components are installed: A new MSSQL 2012 instance named SQLEXPRESS. The Synchronizer database is created and initialized within this instance. The default database name is Sync_HOSTNAME (HOSTNAME is the network host name of the primary Synchronizer server). MSSQL 2012 Management Studio Express Used to manage databases including database backups. Also used to manage the sa account or other security accounts. SQL Server Configuration Manager Used to manage database server configuration. Can be used to manage network settings for the SQLEXPRESS instance. Including the port number, which may be needed by remote Synchronizer servers. SQL Server Browser Service Used to lookup network ports given a database instance name. This service plays a key role when connecting to database instances by name.
Synchronizer Installation: Integrating with an Existing MSSQL Instance
Copyright 2013 Citrix Page 15 XenClient Enterprise 5.0 Synchronizer Database Integration Database Option: Use Existing MSSQL Server If this option is chosen: The full MSSQL 2012 Express server will not be installed. But the MSSQL Native Client component will be installed. It is used by the Synchronizer installer: Create the database on initial Synchronizer install. Backup the database during Synchronizer upgrades. Delete the database for Synchronizer uninstall (if the "delete database" uninstall option is chosen).
Copyright 2013 Citrix Page 16 XenClient Enterprise 5.0 Synchronizer Database Integration External Database Configuration Enter the fully-qualified hostname of the MSSQL database server. Synchronizer installer will create a new database. Default name is the Synchronizer hostname. The database name will include a Sync_ prefix. For example, Center becomes Sync_Center. This must be a local SQL account. Windows accounts are not currently supported. It is not necessary to use the sa account. Database creation privileges are required. The MSSQL instance port or name is required. If the port is defined: Synchronizer will use the port. The instance name is ignored. If the port is left blank: The instance name is required. Synchronizer will connect to the named instance through the SQL Browser Service.
Copyright 2013 Citrix Page 17 XenClient Enterprise 5.0 Synchronizer Database Integration Database Server Credentials Windows Authentication Not Supported MSSQL supports local and Windows authentication methods. But Synchronizer doesn't support Windows authentication. A local SQL account must be used instead. Required Account Permissions Must be able to create the Synchronizer database on the database server. Not possible to use a database that has been pre-created. The account must have full read/write access to the Synchronizer database. The "create database" privilege may be removed after the primary Synchronizer is installed. SA Account (Bundled MSSQL 2012 Express) Initial Synchronizer configuration must use the SA account. This can be changed after the primary Synchronizer is installed: Create a new local SQL account. Grant full read/write access to the Synchronizer database. Then refer to Changing the Database Username and Password.Changing the Database Username and Password
Copyright 2013 Citrix Page 18 XenClient Enterprise 5.0 Synchronizer Database Integration Database Security Policy Issues When integrating with production database servers, two security policy issues may arise. Excessive Privilege Database security policy may not allow the "create database" privilege. Even though this is only a temporary requirement (the privilege can be revoked after installation). Solution #1: Create a new production database instance. Create a new local SQL account with full privileges to the new instance, but no privileges to other instances. Solution #2: Run through Synchronizer installation with the bundled MSSQL 2012 Express option. After installation, the database may be migrated to the production database server. Local SQL Accounts Database security policy may require Windows authentication. Unfortunately this is not currently supported by Synchronizer, a local SQL account is required. If an exception cannot be granted, the only solution may be to install a new copy of MSSQL server and integrate with that instead. Or use the MSSQL 2012 Express bundled with the Synchronizer installer.
Copyright 2013 Citrix Page 20 XenClient Enterprise 5.0 Synchronizer Database Integration Remote Network Connectivity Requirements Connect To… Primary Synchronizer MSSQL Database Active Directory Connect From… Remote Synchronizer Yes. Remote server connects to the primary server to process update requests from remote computers and to download VHD files which are cached locally on the remote server. Yes. The remote server connects directly to the database. If the database connection is lost, the remote Synchronizer cannot function properly. Yes. The remote Synchronizer connects directly to AD for computer registration. Remote Engines No. Engine only connects to the Synchronizer server it is registered to. For remote computers, Engine should be registered to the remote Synchronizer. No. Engine never connects to the database. If Engine needs something from the database, the request is channeled through Synchronizer. No. Engine never connects to Active Directory. If Engine needs something from AD, the request is channeled through Synchronizer. Remote Deployed VMs No. Deployed VMs don't connect to Synchronizer. No. Deployed VMs don't connect to the database. Usually. Not necessary from an XCE point of view, but deployed VMs are usually joined to the domain and must connect to AD for user authentication and access to domain resources.
Copyright 2013 Citrix Page 21 XenClient Enterprise 5.0 Synchronizer Database Integration Remote Server Installation Before Installation On the remote Synchronizer server, open Windows Explorer and navigate to the primary Synchronizer installation folder (using a UNC path as shown). Copy database.properties and key.properties to the Windows desktop on the remote server. These files will be needed during the remote Synchronizer installation. During Installation The Synchronizer installer will ask for the location of the two files copied from the primary Synchronizer. Browse to the Windows desktop. The installer will automatically load the files and use them for remote Synchronizer database integration. After Installation The two files should be deleted from the remote server desktop.
Copyright 2013 Citrix Page 22 XenClient Enterprise 5.0 Synchronizer Database Integration SQL Server Browser Service This service plays an important role when connecting to MSSQL instances by name. It acts as a lookup service, converting an instance name to an instance port. The instance port may change over time, so new connections should always go through the browser service. This is the default configuration when MSSQL 2012 Express is installed by the Synchronizer installer. Connects to the SQLEXPRESS instance to access the Synchronizer database. Synchronizer Replies with the port being used by the SQLEXPRESS instance. Connects on port 1434 to lookup the SQLEXPRESS instance port. SQLEXPRESS Database Instance (dynamic port) Synchronizer Database SQL Server Browser Service (port 1434)
Copyright 2013 Citrix Page 23 XenClient Enterprise 5.0 Synchronizer Database Integration Dynamic Ports and Remote Synchronizer Servers For the primary Synchronizer: Synchronizer usually has direct access to the database with no intervening firewalls, so there are no restrictions on what dynamic port may be used by the SQLEXPRESS instance. The default configuration to connect through the browser service should be valid. But for remote Synchronizer installations: There will typically be a firewall between the remote Synchronizer and the database, especially if the remote Synchronizer connects to the primary network over a WAN link. Port 1434 may be opened in the firewall to allow access to the browser service, but it is not practical to open every dynamic port that may be used by the SQLSERVER instance. The default configuration, which relies on the browser service, may not work. Recommended solution: After installing the primary Synchronizer, shutdown the Synchronizer (Apache Tomcat) service. Configure the SQLEXPRESS instance to use static port 1433 (see Managing the SQLEXPRESS Instance Port). Then restart the instance. Edit database.properties to remove the instance name and port from the JDBC URL: mgmt.srv.database.url=jdbc:sqlserver://localhost;databaseName=NxTop_Center Restart Synchronizer, login to the console, and verify database connectivity.
Copyright 2013 Citrix Page 25 XenClient Enterprise 5.0 Synchronizer Database Integration Verifying Database Connectivity in Synchronizer Console The Server Health Report can be used as a quick check for Synchronizer database connectivity. In the Overview section, select the Servers element, then click the Summary tab. For the Primary Synchronizer Server: Server Health data is stored in the database. If any data is displayed for any server, it means the primary server has database connectivity. For a Remote Synchronizer Server: The remote server health heartbeat is communicated through the database. If the remote server is UP then it must have connected to the database within the last 30 minutes. 30 minutes is the threshold for marking a server DOWN due to lost heartbeats. If a remote server is marked DOWN, it may be for reasons unrelated to the database. For example, the remote server may simply be shutdown.
Copyright 2013 Citrix Page 26 XenClient Enterprise 5.0 Synchronizer Database Integration Verifying Database Connectivity in Synchronizer Logs The main Synchronizer log file is located in the Apache Tomcat installation folder: C:\Program Files\Apache Software Foundation\Tomcat 7.0\logs\nxtop.log Restart Synchronizer (Apache Tomcat service), wait 60 seconds, then open the log file in a text editor. Go to the bottom of the file, then search upwards for a section that looks like this, marking a Synchronizer restart: ============================================================ = XenClient Enterprise Synchronizer v5.0.TP4-16634 = ============================================================ From this point search down for a log entry that look like this: Using JDBC URL 'jdbc:sqlserver://db.acme.net;instanceName=XCE;databaseName=NxTop_Center' Make sure the JDBC URL is correct: Hostname (db.acme.net in this example). Instance Name (XCE in this example, but may be absent if an instance port is provided). Instance Port (Absent from this example, it would normally follow the hostname like db.acme.net:1443). Database Name (NxTop_Center in this example). Then search further down for a log entry that looks like this. This entry confirms Synchronizer has at least basic connectivity to the database. Registered repository 'https://xce.acme.net.net:443/MgmtRepository/NxTop/Download/' at id 1 Finally check for any exceptions related to the database (search for the string "Exception").
Copyright 2013 Citrix Page 27 XenClient Enterprise 5.0 Synchronizer Database Integration Locating Database Files MSSQL will create the Synchronizer database files in a folder like this: C:\Program Files\Microsoft SQL Server\MSSQL11.SQLEXPRESS\MSSQL\DATA The exact folder depends on the version of MSSQL and the database instance. There should be two files: Database Data File:Sync_HOSTNAME.mdf Transaction Log File:Sync_HOSTNAME_log.ldf These are default file names. Actual file names may be different (but should always begin with Sync_). The exact folder and file names can be obtained from MSSQL Studio as shown below. The folder path and file names should be displayed. Some scrolling may be required to display this information. Right-click the Synchronizer database and select Properties. Then select Files in the Database Properties panel.
Copyright 2013 Citrix Page 28 XenClient Enterprise 5.0 Synchronizer Database Integration Relocating Database Files It may be desirable to move the MSSQL database files to a different location. This is usually done for backup purposes. One possible scenario: Synchronizer is installed on a SAN volume attached to the Windows server. Backing up Synchronizer data is accomplished through SAN volume snapshots. The Synchronizer database is moved to the SAN volume for inclusion in the backups. The Apache folder should also be relocated, it contains critical data that must be backed up. Important note regarding the detach/reattach strategy outlined below! The database is being detached then reattached to the exact same database instance. The process for migrating the database between instances is more complex. 1.Shutdown all Synchronizer servers (primary and remote). 2.Login to MSSQL Studio with Administrator privileges. 3.Take a backup of the Synchronizer database. 4.Detach the Synchronizer database (right-click the database entry, select Tasks, then Detach). 5.Copy and paste (not cut and paste!) both database files to the new location. 6.Use a file checksum calculator or other tool to verify integrity of the copied files. 7.Delete the original files. 8.In MSSQL Studio, right-click the Databases element and select Attach. 9.Browse to the location of the relocated database data file. 10.The database should be added. Browse through a few tables to verify it still contains data. 11.Restart the primary Synchronizer, login, and verify database connectivity. 12.Restart any remote Synchronizer servers.
Copyright 2013 Citrix Page 29 XenClient Enterprise 5.0 Synchronizer Database Integration Changing the Database Username and Password Database credentials are usually encrypted in the database.properties file like this: mgmt.srv.database.user=@TIx2z8j62XuNnL5OH7ngcQ== mgmt.srv.database.password=@2xj70t2lksYbKbSHEttPeA== The following process can be used to change the credentials. 1.Shutdown Synchronizer (stop the Apache Tomcat Windows service). 2.Make a backup copy of database.properties. 3.Edit database.properties to set the new username and password in clear text: mgmt.srv.database.user=newuser mgmt.srv.database.password=newpassword 4.Restart Synchronizer. During startup, Synchronizer will re-encrypt the database credentials. If remote Synchronizer servers are deployed: In step 1, shutdown all remote servers first, then the primary server. In step 2, database.properties must be modified on all servers. In step 3, start the primary server and verify database connectivity before starting the remote servers.
Copyright 2013 Citrix Page 30 XenClient Enterprise 5.0 Synchronizer Database Integration Purging Database Event Tables A simple command-line tool is available for purging events from the database. Only recommended if the Synchronizer database has grown to an abnormally large size. What events get deleted? All events between the specified dates… …except for events related to creation or deletion of managed objects. To run the tool on the primary Synchronizer server: Open a command prompt (DOS box) with Administrator privileges. Navigate to this folder: C:\Program Files\Citrix\Synchronizer\bin Run a command like this: purgeEvents.cmd -from01/01/2010 -to12/31/2010 No space between -from or -to and the following dates. Dates are in MM/dd/yyyy format. The primary Synchronizer does not need to be running to use this tool.
Copyright 2013 Citrix Page 31 XenClient Enterprise 5.0 Synchronizer Database Integration Migrating from MSSQL Express to a Production MSSQL Server If Synchronizer is initially installed with the bundled MSSQL 2012 Express, the database may be migrated to a production MSSQL server later. The following steps outline the process. Review the migration with the MSSQL administrator before beginning. 1.Shutdown and disable all Synchronizer servers (remote servers first, then the primary server last). Shutdown and disable the Windows service Apache Tomcat 7. Disabling the service prevents accidental restart during the migration. 2.In the MSSQL Express Management Studio: Backup the Synchronizer database to a new backup file. Detach the Synchronizer database. 3.Shutdown and disable MSSQL Express. Shutdown and disable the Windows service SQL Server (SQLEXPRESS). This ensures that Synchronizer can't accidentally reconnect to the old database. 4.Transfer of Synchronizer database files: Move the data and log files to an archive repository (see Locating Database Files).Locating Database Files Move the new backup file to a convenient location for import into the production MSSQL server. 5.In the production MSSQL Management Studio: * Import the Synchronizer data, creating a new database with the same name. Create a new local SQL account with read/write access to the new database. 6.Update database.properties for the primary Synchronizer. Update the host name in the JDBC URL. Update or add the instance port or instance name to the JDBC URL. Update the SQL account name and password (see Changing the Database Username and Password).Changing the Database Username and Password 7.Start the primary Synchronizer. Verify database connectivity and make sure Synchronizer data appears intact. 8.For each remote Synchronizer server: Replicate the updated database.properties file to the remote Synchronizer server. Start the remote Synchronizer and verify database connectivity.
Copyright 2013 Citrix Page 32 XenClient Enterprise 5.0 Synchronizer Database Integration Migrating from MSSQL Express to a Production MSSQL Server If Synchronizer is initially installed with the bundled MSSQL 2012 Express, the database may be migrated to a production MSSQL server later. The following steps outline the process. Review the migration with the MSSQL administrator before beginning. 1.Shutdown and disable all Synchronizer servers (remote servers first, then the primary server last). Shutdown and disable the Windows service Apache Tomcat 7. Disabling the service prevents accidental restart during the migration. 2.In the MSSQL Express Management Studio: Backup the Synchronizer database to a new backup file (see Synchronizer Database Export Example).Synchronizer Database Export Example Detach the Synchronizer database (right-click the database entry, select Tasks, then Detach). 3.Shutdown and disable MSSQL Express. Shutdown and disable the Windows service SQL Server (SQLEXPRESS). This ensures that Synchronizer can't accidentally reconnect to the old database. 4.Transfer of Synchronizer database files: Move the data and log files to an archive repository (see Locating Database Files).Locating Database Files Move the new backup file to a convenient location for import into the production MSSQL server. 5.In the production MSSQL Management Studio: Import the Synchronizer database by restoring from backup (see Synchronizer Database Import Example).Synchronizer Database Import Example Create a new local SQL account with read/write access to the new database. 6.Update database.properties for the primary Synchronizer. Update the host name in the JDBC URL. Update or add the instance port or instance name to the JDBC URL. Update the SQL account name and password (see Changing the Database Username and Password).Changing the Database Username and Password 7.Start the primary Synchronizer. Verify database connectivity and make sure Synchronizer data appears intact. 8.For each remote Synchronizer server: Replicate the updated database.properties file to the remote Synchronizer server. Start the remote Synchronizer and verify database connectivity.
Copyright 2013 Citrix Page 33 XenClient Enterprise 5.0 Synchronizer Database Integration Synchronizer Database Export Example MSSQL provides several options for exporting a database. One way to export data is to backup the database to a new backup file so it can be restored later or imported into a different MSSQL server. This is the recommended export method if you need to send your Synchronizer database to Citrix technical support for analysis. In MSSQL Studio, right-click the Synchronizer database and choose Tasks then Back Up. In the Back Up Database panel: In the Source section, specify a full backup. In the Destination section, specify a new backup file in a convenient location. When the backup is complete a new backup file should be created. This is the file that should be imported into a different MSSQL server or sent to Citrix technical support for analysis.
Copyright 2013 Citrix Page 34 XenClient Enterprise 5.0 Synchronizer Database Integration Synchronizer Database Import Example MSSQL provides several options for database import. One way is to restore a database backup that was taken from a different MSSQL server. This is how Citrix usually imports Synchronizer databases sent in by customers for analysis. Check with your MSSQL administrator for specific guidance depending on what you are trying to accomplish. In MSSQL Studio, right-click the Databases element then select Restore Database. In the Source section: Select the Device option then click the browse (…) button. Add the database backup file as the restore source. In the Destination section: The destination database should be set automatically. It should be the same as the original Synchronizer database name. If a database already exists with that name it will be overwritten. When the restore is complete, a new database should appear in MSSQL Studio. It should be an exact copy of the original database at the time the backup was taken.
Copyright 2013 Citrix Page 36 XenClient Enterprise 5.0 Synchronizer Database Integration Database Reporting Running SQL queries against the Synchronizer database for reporting purposes is possible but it is considered to be outside the scope of supported product functionality. Support Status There is no official support for database reporting in XenClient Enterprise. Database schema is undocumented and may change at any time. Citrix Technical support is not obligated to assist with issues in this area. At Your Own Risk Malformed queries can damage data in ways that may be difficult or impossible to repair. Complex queries may interfere with Synchronizer operations (locking issues or resource exhaustion). To minimize risk, shutdown Synchronizer (primary and remote servers) and backup the database before running a query. For Information Only Synchronizer console is the "official and supported" way to get information about managed objects. Be careful about taking action based on the result of a database report. Verify the report results with the Synchronizer console first. Best Practices Always use read-only MSSQL connections to avoid accidental data loss or modification. Do not use the Synchronizer/MSSQL integration account (it has full read/write access). Don't run overly complex queries. If MSSQL can't process a query in 10 seconds, it is probably too complex.
Copyright 2013 Citrix Page 37 XenClient Enterprise 5.0 Synchronizer Database Integration Sample Database Reports Sample Report Notes The following reports are examples of what customers have requested in the past. They have all been tested with Synchronizer version 5.0 but may not work with post-5.0 releases due to potential schema changes. Running the Sample Reports Consult with your MSSQL administrator for specific guidance. One possible process: Temporarily shutdown the primary Synchronizer and all remote Synchronizer servers. Login to MSSQL Management Studio with read-only access to the Synchronizer database. Take a backup of the Synchronizer database. Load and run the report query, then save or take note of the results. Restart Synchronizer, login to the console, verify the query results and take the appropriate administrative actions.
Copyright 2013 Citrix Page 38 XenClient Enterprise 5.0 Synchronizer Database Integration Synchronizer Event Report declare @d1 date, @d2 date, @minsev int; -- Last 7 days. set @d1 = DateAdd(day, -7, GetDate()); set @d2 = GetDate(); -- Between specific dates. set @d1 = '1-jul-2013'; set @d2 = '31-jul-2013'; -- 0 = all, 1 = errors and warnings, 2 = errors only set @minsev = 2; select timestamp as 'Event Timestamp', eventSeverity as 'Event Severity', sourceShortcutString as 'Event Source', summary as 'Event Summary', details as 'Event Details' from BaseEvent where timestamp >= @d1 and timestamp <= @d2 and eventSeverity >= @minsev order by timestamp desc This report shows Synchronizer event messages filtered by date and/or severity.
Copyright 2013 Citrix Page 39 XenClient Enterprise 5.0 Synchronizer Database Integration Computer Report select c.name as 'Computer Name', u.name as 'Registered User', ntc.name as 'Registered Server', c.assetTag as 'Asset Tag', c.cpuCount as 'CPU Count', c.cpuDescription as 'CPU Description', cast(c.memoryInMb / 1024 as decimal(8,1)) as 'Memory (GB)', c.ipAddress as 'IP Address', c.manufacturer as 'Manufacturer', c.model as 'Model', c.diskEncrypted as 'Encryption', c.primaryVersion as 'Engine Version', c.clientCheckinTimestamp as 'Last Check-In', cast(c.diskBytes / 1073741824 as decimal(8,1)) as 'Total Disk Space (GB)' from Computer c, User_Table u, NxTopCenter ntc where c.user_id = u.id and u.nxTopCenter_id = ntc.id This report displays information about registered computers.
Copyright 2013 Citrix Page 40 XenClient Enterprise 5.0 Synchronizer Database Integration Deployed VM Version Report select u.name as 'User Name', vd.name as 'Image Name', ud.stageVersion as 'Staged', ud.version as 'Reported Version', vdv.versionNumber as 'Expected Version' from UserDesktop ud, VirtualDesktop vd, User_Table u, VirtualDesktopVersion vdv where u.id = ud.user_id and vd.id = ud.desktop_id and ( ud.stageVersion = 0 and vdv.id = vd.currentVersion_id and ud.version != vdv.versionNumber ) or ( ud.stageVersion != 0 and vdv.id = vd.stageVersion_id and ud.version != vdv.versionNumber ) order by u.name This report will display users who are not running the assigned version of a VM.
Copyright 2013 Citrix Page 41 XenClient Enterprise 5.0 Synchronizer Database Integration Engine Software Version Report select c.name as 'Computer Name', c.ipAddress as 'Computer IP Address', c.manufacturer 'Computer Manufacturer', c.model as 'Computer Model', c.primaryVersion as 'Current Engine Version', c.secondaryVersion as 'Previous Engine Version', c.upgradeState as 'Engine Upgrade State', k.name as 'Assigned Engine Upgrade Kit Name', k.version as 'Assigned Engine Upgrade Kit Version' from Computer c, NxTopClientKit k where c.upgradeState != 'NORMAL' or ( c.desiredVersion_id != NULL and c.desiredVersion_id = k.id and c.primaryVersion != k.version ) This report shows computers that are not running the version of Engine software assigned in the Synchronizer. It also shows computers that experienced an Engine software upgrade failure.
Copyright 2013 Citrix Page 42 XenClient Enterprise 5.0 Synchronizer Database Integration Deployed VM MAC and Computer Name Report select u.name as 'User Name', vd.name as 'VM Image Name', ud.hostname as 'VM Computer Name', ud.macAddress as 'VM MAC Address' from User_Table u, VirtualDesktop vd, UserDesktop ud where UserDesktop.desktop_id = User_Table.id and UserDesktop.desktop_id = VirtualDesktop.id This report shows the MAC address and Windows computer name generated by Synchronizer for deployed VMs. The actual Windows computer name might be different, if it was changed in the deployed VM.
Copyright 2013 Citrix Page 43 XenClient Enterprise 5.0 Synchronizer Database Integration Backup Usage Report select top 20 u.name as 'User Name', vd.name as 'VM Name', (select count(*) from Snapshot where vmBackup_id = vmb.id) as 'Backup Count', ((select max(totalSize) from Snapshot where vmBackup_id = vmb.id) / 1073741824) as 'Max Uncompressed (GB)', ((select max(totalCompressedSize) from Snapshot where vmBackup_id = vmb.id) / 1073741824) as 'Max Compressed (GB)', (select max(timestamp) from Snapshot where vmBackup_id = vmb.id) as 'Most Recent' from User_Table u, VirtualDesktop vd, VmBackup vmb, UserDesktop ud where ud.user_id = u.id and ud.desktop_id = vd.id and vmb.userDesktop_id = ud.id order by 'Max Uncompressed (GB)' desc -- Or 'Backup Count' This report displays the largest backups on Synchronizer, or users with the largest number of outstanding backups.